alekspetrov/navigator/nav-task

Name: nav-task
Author: alekspetrov

Claude Code and agent skill by alekspetrov/navigator

Trust tier 3

community

Source check pending

Checking that the SKILL.md file is still in the repository.

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".

Install

npx vskill@latest install alekspetrov/navigator/nav-task

SKILL.md

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):

bash

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:

bash

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:

markdown

# 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:

markdown

# 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:

markdown

## 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:

bash

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:

typescript

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

If PM tool is GitHub:

bash

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!

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 95 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/nav-task/SKILL.md

Popularity

Repository stars: 160
Repository forks: 8
7-day trend score: 25

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 27 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/alekspetrov/navigator/nav-task/badge)](https://verified-skill.com/skills/alekspetrov/navigator/nav-task)

Something wrong with this skill or its page? Tell us.