qf-studio / nav-task

Name: qf-studio/nav-task
Author: qf-studio

Manage Navigator task documentation - create implementation plans, archive completed tasks, update task index. Use when user starts new feature, completes work, or says "document this feature".

Version

SKILL.md

15.7 KB

⚠This file contains 2 character(s) that do not render as themselves (U+FE0F). They are shown highlighted below.

Navigator Task Manager Skill

Create and manage task documentation - implementation plans that capture what was built, how, and why.

When to Invoke

Invoke this skill when the user:

Says "document this feature", "archive this task"
Says "create task doc for...", "document what I built"
Completes a feature and mentions "done", "finished", "complete"
Starts new feature and says "create implementation plan"

DO NOT invoke if:

User is asking about existing tasks (use Read, not creation)
Creating SOPs (that's nav-sop skill)
Updating system docs (different skill)

Execution Steps

Step 1: Determine Task ID

If user provided task ID (e.g., "TASK-01", "GH-123"):

Use their ID directly

If no ID provided, run the generator — it reads task_id_source from
.agent/.nav-config.json (default local):

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-task/functions/task_id_generator.py" \
  --title "{feature name}" --body "{one-line summary}" --json

task_id_source: local (solo repos) — next sequential {task_prefix}-NN from
.agent/tasks/ (last is TASK-05 → TASK-06). --title is ignored.
task_id_source: github (team repos, GH-32) — creates the GitHub issue first via
gh issue create and returns GH-<n>; the doc is .agent/tasks/GH-<n>-{slug}.md.
Issue numbers are allocated by GitHub, so two contributors branching at once can
never mint the same ID, and Pilot already addresses tasks as GH-<n>. Add
--label pilot (or any label) when the issue should be picked up. A failing gh
(no auth, no network) is an error — do not fall back to a local number; tell the
user and stop.
Existing TASK-NN docs keep working either way; the index, graph sync and
session-start listing accept any PREFIX-<n> filename.
In the doc template below, TASK-{XX} stands for whichever ID came back.

Step 2: Determine Action (Create vs Archive)

Creating new task (starting feature):

User: "Create task doc for OAuth implementation"
→ Action: CREATE
→ Generate empty implementation plan template

Archiving completed task (feature done):

User: "Document this OAuth feature I just built"
→ Action: ARCHIVE
→ Generate implementation plan from conversation

Step 2.5: Recall Prior Knowledge (CREATE flow only, v6.17.0+)

Before writing the plan, query the knowledge graph for memories relevant
to this feature — pitfalls and patterns the project has already paid for:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

if [ -f ".agent/knowledge/graph.json" ]; then
  python3 "$PLUGIN_DIR/skills/nav-graph/functions/memory_recall.py" \
    --concepts "{comma-separated concepts inferred from the feature description}" \
    --format markdown --limit 5
fi

Infer concepts from the feature description using the same keyword
families as task_to_graph.extract_concepts_from_task (auth, database,
api, frontend, testing, …) — alias resolution absorbs abbreviations.
Empty output → skip silently. Do not add the section; do not mention
the absence.
Non-empty output → include it as the ## Known Pitfalls & Patterns
section in the template below, and **reflect each recalled pitfall in
the Implementation phases** (a recalled pitfall that doesn't change the
plan wasn't really factored in).

Step 3A: Create New Task (If Starting Feature)

Generate task document from template:

# TASK-{XX}: {Feature Name}

**Status**: 🚧 In Progress
**Created**: {YYYY-MM-DD}
**Assignee**: {from PM tool or "Manual"}

---

## Context

**Problem**:
[What problem does this solve?]

**Goal**:
[What are we building?]

---

## Known Pitfalls & Patterns

<!-- From knowledge graph (Step 2.5). OMIT this section entirely if recall
     returned nothing. Each recalled pitfall must be reflected in the
     Implementation phases below. -->

- **PITFALL** (90%, mem-XXX): [recalled summary]

---

## Acceptance Criteria

Concrete, checkable outcomes — written so anyone (human or AI) can verify them.

- [ ] [Specific, observable outcome]
- [ ] [Another outcome]
- [ ] [Edge case handled]

---

## Implementation

### Phase 1: {Name}
**Goal**: [What this phase accomplishes]

**Tasks**:
- [ ] [Specific task]
- [ ] [Another task]

**Files**:
- `path/to/file.ts` - [Purpose]

### Phase 2: {Name}
...

---

## Out of Scope

Explicit non-goals — what this task deliberately does not address.

- [What's deferred to a future task]
- [Adjacent change being avoided]

---

## Technical Decisions

| Decision | Options Considered | Chosen | Reasoning |
|----------|-------------------|--------|-----------|
| [What] | [Option A, B, C] | [Chosen] | [Why] |

---

## Verify

Run these commands to validate the implementation:

Run tests

[test command for this feature]

Type check

[type check command]

Build

[build command]


---

## Done

Observable outcomes that prove completion:

- [ ] [Specific file/API exists and exports expected interface]
- [ ] [Tests pass - specify count or coverage target]
- [ ] [Build succeeds without errors]
- [ ] [User-observable behavior works as specified]

---

## Refs

- [Source plan / design doc / parent issue]
- [Related ticket]

---

## Notes

[Any additional context, links, references]

---

**Last Updated**: {YYYY-MM-DD}

Save to: .agent/tasks/TASK-{XX}-{slug}.md

Step 3B: Archive Completed Task (If Feature Done)

Generate task document from conversation:

Analyze conversation (last 30-50 messages):
- What was built?
- How was it implemented?
- What decisions were made?
- What files were modified?
Generate implementation plan:

# TASK-{XX}: {Feature Name}

**Status**: ✅ Completed
**Created**: {YYYY-MM-DD}
**Completed**: {YYYY-MM-DD}

---

## What Was Built

[1-2 paragraph summary of the feature]

---

## Implementation

### Phase 1: {Actual phase completed}
**Completed**: {Date}

**Changes**:
- Created `src/auth/oauth.ts` - OAuth provider integration
- Modified `src/routes/auth.ts` - Added login/logout endpoints
- Updated `src/config/passport.ts` - Passport configuration

**Key Code**:

// Example of key implementation
export const oauthLogin = async (req, res) => {
// Implementation details
};


### Phase 2: {Next phase}
...

---

## Technical Decisions

| Decision | Options | Chosen | Reasoning |
|----------|---------|--------|-----------|
| Auth library | next-auth, passport.js, auth0 | passport.js | Better control over OAuth flow, smaller bundle |
| Token storage | localStorage, cookies, sessionStorage | httpOnly cookies | XSS protection, automatic transmission |
| Session store | memory, Redis, PostgreSQL | Redis | Fast, scalable, separate from DB |

---

## Files Modified

- `src/auth/oauth.ts` (created) - OAuth integration
- `src/routes/auth.ts` (modified) - Added auth endpoints
- `src/config/passport.ts` (created) - Passport setup
- `tests/auth.test.ts` (created) - Auth tests
- `README.md` (updated) - OAuth setup instructions

---

## Challenges & Solutions

**Challenge**: OAuth callback URL mismatch
- **Problem**: Redirects failed in production
- **Solution**: Added environment-specific callback URLs
- **Commit**: abc1234

**Challenge**: Session persistence across restarts
- **Problem**: Users logged out on server restart
- **Solution**: Redis session store
- **Commit**: def5678

---

## Testing

- ✅ Unit tests: `src/auth/*.test.ts` (15 tests, 100% coverage)
- ✅ Integration tests: OAuth flow end-to-end
- ✅ Manual testing: Tested with Google, GitHub providers

---

## Documentation

- ✅ README updated with OAuth setup instructions
- ✅ Environment variables documented in `.env.example`
- ✅ API endpoints documented in `docs/api.md`

---

## Verify

Commands executed to validate:

Actual commands run during verification

npm test src/auth
npm run type-check
npm run build


**Results**: All passed ✅

---

## Done

Outcomes confirmed:

- [x] `src/auth/oauth.ts` exports OAuth provider integration
- [x] All tests pass (15 tests, 100% coverage)
- [x] Build succeeds without errors
- [x] OAuth login/logout flows work correctly

---

## Related

**SOPs Created**:
- `.agent/sops/integrations/oauth-setup.md`

**System Docs Updated**:
- `.agent/system/project-architecture.md` (added auth section)

---

**Completed**: {YYYY-MM-DD}
**Implementation Time**: {X hours/days}

Save to: .agent/tasks/TASK-{XX}-{slug}.md

Step 3.5: Verify Interpretation (ToM Checkpoint - Archive Mode Only) [EXECUTE]

IMPORTANT: This step MUST be executed when archiving tasks (not creating new ones).

Before committing archive documentation, confirm interpretation with user.

Display verification (only for ARCHIVE action):

I extracted this from our session:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What was built:
- {FEATURE_SUMMARY}

Key decisions captured:
- {DECISION_1}: {REASONING_1}
- {DECISION_2}: {REASONING_2}

Files changed: {COUNT} total
- {FILE_1} ({ACTION}: {PURPOSE})
- {FILE_2} ({ACTION}: {PURPOSE})

Challenges solved:
- {CHALLENGE_1}: {SOLUTION_1}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Corrections needed? [Enter to proceed / type corrections]

Always verify for ARCHIVE because:

Extracting from conversation is inference-based
User may have made decisions not explicitly stated
Some files may have been modified outside conversation
Ensures accurate historical record

Skip verification for CREATE because:

Template is mostly empty
User fills in details themselves
No inference risk

Step 4: Update Navigator Index

Edit .agent/DEVELOPMENT-README.md to add task to index:

## Active Tasks

- **TASK-{XX}**: {Feature Name} (Status: In Progress/Completed)
  - File: `.agent/tasks/TASK-{XX}-{slug}.md`
  - Started: {Date}
  - [Completed: {Date}]

Keep index organized (active tasks first, completed below).

Step 4.5: Sync to Knowledge Graph (v6.0.0+)

If knowledge graph exists, sync task to graph:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
if [ -f ".agent/knowledge/graph.json" ]; then
  python3 "$PLUGIN_DIR/skills/nav-graph/functions/task_to_graph.py" \
    --action add \
    --task-path ".agent/tasks/TASK-{XX}-{slug}.md" \
    --graph-path .agent/knowledge/graph.json
fi

What this does:

Extracts concepts from task content (auth, api, testing, etc.)
Adds task node to graph with status and concepts
Creates implements edges from task to concepts
For completed tasks: Extracts Technical Decisions as decision memories

Output:

Added task: TASK-XX
Title: {Feature Name}
Status: completed
Concepts: auth, api, testing
Decisions extracted: 2

This makes the task queryable via "What do we know about auth?" and preserves architectural decisions as persistent memories.

Step 5: Update PM Tool (If Configured)

If PM tool is Linear:

create_comment({
  issueId: "TASK-XX",
  body: "📚 Implementation plan documented: .agent/tasks/TASK-XX-feature.md"
})

If PM tool is GitHub:

gh issue comment {ISSUE-NUMBER} -b "📚 Implementation plan: .agent/tasks/TASK-XX-feature.md"

If PM tool is none:
Skip PM update.

Step 6: Confirm Success

Show completion message:

✅ Task documentation created!

Task: TASK-{XX} - {Feature Name}
File: .agent/tasks/TASK-{XX}-{slug}.md
Size: {X} KB (~{Y} tokens)

📋 Contains:
- Implementation phases
- Technical decisions
- Files modified
- [If archived: Challenges & solutions]
- [If archived: Testing & documentation]

🔗 Navigator index updated
[If PM tool: PM tool comment added]

To reference later:
Read .agent/tasks/TASK-{XX}-{slug}.md

Task Document Template Structure

For New Tasks (Planning)

Context (problem/goal)
Acceptance criteria (- [ ] checkable outcomes)
Implementation (phases)
Out of scope (explicit non-goals)
Technical decisions (to be made)
Verify + Done (validation + completion)
Refs (sources/related)

For Completed Tasks (Archive)

What was built (summary)
Implementation (actual phases)
Technical decisions (what was chosen)
Files modified
Challenges & solutions
Testing & documentation

Common Use Cases

Starting New Feature

User: "Create task doc for payments integration"
→ Generates TASK-07-payments.md
→ Empty template for planning
→ User fills in as they work

Completing Feature

User: "Document the auth feature I just finished"
→ Analyzes conversation
→ Generates TASK-06-auth.md
→ Complete implementation record
→ Archives for future reference

Mid-Feature Update

User: "Update TASK-05 with OAuth decision"
→ Reads existing TASK-05-auth.md
→ Adds to Technical Decisions section
→ Preserves rest of document

Error Handling

Navigator not initialized:

❌ .agent/tasks/ directory not found

Run /nav:init to set up Navigator structure first.

Task ID already exists (for creation):

⚠‹VARIATION SELECTOR U+FE0F›  TASK-{XX} already exists

Options:
1. Read existing task
2. Use different ID
3. Archive/overwrite existing

Your choice [1-3]:

Insufficient context to archive:

⚠‹VARIATION SELECTOR U+FE0F›  Not enough conversation context to generate implementation plan

Consider:
- Provide more details about what was built
- Manually create task doc
- Skip archiving

Continue with template? [y/N]:

Success Criteria

Task documentation is successful when:

[ ] Task file created in .agent/tasks/
[ ] Filename follows convention: TASK-{XX}-{slug}.md
[ ] Contains all required sections
[ ] Navigator index updated
[ ] PM tool updated (if configured)
[ ] User can reference task later

Scripts

generate_task.py: Create task documentation from conversation

Input: Conversation history, task ID
Output: Formatted task markdown

update_index.py: Update DEVELOPMENT-README.md task index

Input: New task info
Output: Updated index

Best Practices

Good task slugs:

oauth-implementation (descriptive)
stripe-payment-flow (clear purpose)
user-profile-page (specific feature)

Bad task slugs:

feature (too vague)
fix (not descriptive)
task1 (meaningless)

When to create task docs:

✅ Starting major feature (> 1 day work)
✅ Completing any feature (archive)
✅ Complex implementation (capture decisions)
❌ Tiny bug fixes (use SOPs instead)
❌ Exploratory work (wait until direction clear)

Notes

Task docs are living documents:

Created when starting feature (template)
Updated during implementation (decisions)
Finalized when complete (archive)

They serve as:

Planning tool (before implementation)
Progress tracker (during implementation)
Historical record (after completion)
Knowledge base (for team/future)

This skill provides same functionality as /nav:doc feature command but with natural language invocation.