Initial commit

2025-11-29 17:51:59 +08:00
commit 38e80921c8
89 changed files with 20480 additions and 0 deletions
--- a/skills/nav-task/SKILL.md
+++ b/skills/nav-task/SKILL.md
@@ -0,0 +1,441 @@
+---
+name: nav-task
+description: 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".
+allowed-tools: Read, Write, Edit, Bash
+version: 1.0.0
+---
+
+# 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**:
+- Read `.agent/.nav-config.json` for `task_prefix`
+- Check existing tasks: `ls .agent/tasks/*.md`
+- Generate next number: `{prefix}-{next-number}`
+- Example: Last task is TASK-05, create TASK-06
+
+### 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 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?]
+
+**Success Criteria**:
+- [ ] [Specific measurable outcome]
+- [ ] [Another outcome]
+
+---
+
+## Implementation Plan
+
+### Phase 1: {Name}
+**Goal**: [What this phase accomplishes]
+
+**Tasks**:
+- [ ] [Specific task]
+- [ ] [Another task]
+
+**Files**:
+- `path/to/file.ts` - [Purpose]
+
+### Phase 2: {Name}
+...
+
+---
+
+## Technical Decisions
+
+| Decision | Options Considered | Chosen | Reasoning |
+|----------|-------------------|--------|-----------|
+| [What] | [Option A, B, C] | [Chosen] | [Why] |
+
+---
+
+## Dependencies
+
+**Requires**:
+- [ ] {prerequisite task or setup}
+
+**Blocks**:
+- [ ] {tasks waiting on this}
+
+---
+
+## Notes
+
+[Any additional context, links, references]
+
+---
+
+## Completion Checklist
+
+Before marking complete:
+- [ ] Implementation finished
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] Code reviewed (if team)
+- [ ] Deployed/merged
+
+---
+
+**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:
+
+1. **Analyze conversation** (last 30-50 messages):
+   - What was built?
+   - How was it implemented?
+   - What decisions were made?
+   - What files were modified?
+
+2. **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**:
+```typescript
+// 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`
+
+---
+
+## 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 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 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!
+
+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)
+1. Context (problem/goal)
+2. Implementation plan (phases)
+3. Technical decisions (to be made)
+4. Dependencies
+5. Completion checklist
+
+### For Completed Tasks (Archive)
+1. What was built (summary)
+2. Implementation (actual phases)
+3. Technical decisions (what was chosen)
+4. Files modified
+5. Challenges & solutions
+6. 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)**:
+```
+⚠️  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**:
+```
+⚠️  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.
--- a/skills/nav-task/functions/index_updater.py
+++ b/skills/nav-task/functions/index_updater.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""
+Update DEVELOPMENT-README.md task index with new task entry.
+"""
+
+import os
+import sys
+import re
+from datetime import datetime
+
+def update_task_index(task_file, status="Planning", description=""):
+    """
+    Add task entry to DEVELOPMENT-README.md index.
+
+    Args:
+        task_file: Task filename (e.g., TASK-10-feature-name.md)
+        status: Task status (Planning, In Progress, Completed)
+        description: Short task description
+
+    Returns:
+        bool: True if updated successfully
+    """
+    readme_path = ".agent/DEVELOPMENT-README.md"
+
+    if not os.path.exists(readme_path):
+        print(f"Error: {readme_path} not found", file=sys.stderr)
+        return False
+
+    # Extract task ID and title from filename
+    match = re.match(r'(TASK-\d+)-(.*?)\.md', task_file)
+    if not match:
+        print(f"Error: Invalid task filename format: {task_file}", file=sys.stderr)
+        return False
+
+    task_id = match.group(1)
+    task_slug = match.group(2).replace('-', ' ').title()
+
+    # Read current README
+    with open(readme_path, 'r') as f:
+        content = f.read()
+
+    # Find the task index section
+    task_section_pattern = r'(### Implementation Plans \(`tasks/`\).*?)(###|\Z)'
+    task_section_match = re.search(task_section_pattern, content, re.DOTALL)
+
+    if not task_section_match:
+        print("Error: Could not find task index section", file=sys.stderr)
+        return False
+
+    # Create new task entry
+    status_emoji = {
+        "Planning": "📋",
+        "In Progress": "🚧",
+        "Completed": "✅"
+    }.get(status, "📋")
+
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    new_entry = f"""
+#### [{task_id}: {task_slug}](./tasks/{task_file})
+**Status**: {status_emoji} {status}
+**Created**: {today}
+
+**What**: {description or "Description pending"}
+
+---
+"""
+
+    # Insert before the next section marker
+    task_section = task_section_match.group(1)
+    rest_of_doc = content[task_section_match.end(1):]
+
+    # Add new entry at the end of task section
+    updated_section = task_section.rstrip() + "\n" + new_entry
+    updated_content = content[:task_section_match.start(1)] + updated_section + rest_of_doc
+
+    # Write back
+    with open(readme_path, 'w') as f:
+        f.write(updated_content)
+
+    print(f"✅ Added {task_id} to DEVELOPMENT-README.md index")
+    return True
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: index_updater.py <task-file> [status] [description]", file=sys.stderr)
+        sys.exit(1)
+
+    task_file = sys.argv[1]
+    status = sys.argv[2] if len(sys.argv) > 2 else "Planning"
+    description = sys.argv[3] if len(sys.argv) > 3 else ""
+
+    success = update_task_index(task_file, status, description)
+    sys.exit(0 if success else 1)
--- a/skills/nav-task/functions/task_formatter.py
+++ b/skills/nav-task/functions/task_formatter.py
@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Format task markdown with proper structure and metadata.
+"""
+
+import sys
+import argparse
+from datetime import datetime
+
+def format_task(title, task_id, priority="Medium", complexity="Medium", status="Planning"):
+    """
+    Generate formatted task markdown.
+
+    Args:
+        title: Task title
+        task_id: Task ID (e.g., TASK-10)
+        priority: Priority level (Low, Medium, High, Critical)
+        complexity: Complexity level (Low, Medium, High)
+        status: Task status (Planning, In Progress, Completed)
+
+    Returns:
+        str: Formatted markdown content
+    """
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    template = f"""# {task_id}: {title}
+
+**Created**: {today}
+**Status**: {status}
+**Priority**: {priority}
+**Complexity**: {complexity}
+
+---
+
+## Context
+
+[Describe the problem, feature request, or improvement needed]
+
+**Problem**: [What needs to be solved?]
+
+**Goal**: [What should be achieved?]
+
+---
+
+## Implementation Plan
+
+### Phase 1: [Phase Name]
+
+**Tasks**:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+**Expected Outcome**: [What this phase delivers]
+
+---
+
+## Success Metrics
+
+**Functionality**:
+- [ ] Feature works as expected
+- [ ] Edge cases handled
+- [ ] Error handling implemented
+
+**Quality**:
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] Code reviewed
+
+**Token Efficiency** (if applicable):
+- [ ] Token usage measured
+- [ ] Optimization targets met
+- [ ] No context pollution
+
+---
+
+## Testing Plan
+
+1. **Unit tests**: [What to test]
+2. **Integration tests**: [What to test]
+3. **Manual testing**: [Steps to verify]
+
+---
+
+## Related Tasks
+
+- [Link to related tasks]
+
+---
+
+## Notes
+
+- [Additional context, decisions, or considerations]
+
+---
+
+**Task created**: {today}
+**Priority**: {priority}
+**Effort**: {complexity}
+"""
+    return template
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Format Navigator task markdown")
+    parser.add_argument("--title", required=True, help="Task title")
+    parser.add_argument("--id", required=True, help="Task ID (e.g., TASK-10)")
+    parser.add_argument("--priority", default="Medium", choices=["Low", "Medium", "High", "Critical"])
+    parser.add_argument("--complexity", default="Medium", choices=["Low", "Medium", "High"])
+    parser.add_argument("--status", default="Planning", choices=["Planning", "In Progress", "Completed"])
+
+    args = parser.parse_args()
+
+    output = format_task(
+        title=args.title,
+        task_id=args.id,
+        priority=args.priority,
+        complexity=args.complexity,
+        status=args.status
+    )
+
+    print(output)
--- a/skills/nav-task/functions/task_id_generator.py
+++ b/skills/nav-task/functions/task_id_generator.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Generate next sequential TASK-XX ID by scanning existing task files.
+"""
+
+import os
+import re
+import sys
+
+def get_next_task_id(agent_dir=".agent", prefix="TASK"):
+    """
+    Scan tasks/ directory and return next available TASK-XX ID.
+
+    Args:
+        agent_dir: Path to .agent directory (default: .agent)
+        prefix: Task ID prefix (default: TASK)
+
+    Returns:
+        str: Next task ID (e.g., "TASK-10")
+    """
+    tasks_dir = os.path.join(agent_dir, "tasks")
+
+    if not os.path.exists(tasks_dir):
+        return f"{prefix}-01"
+
+    # Find all task files matching pattern TASK-XX-*.md
+    task_pattern = re.compile(rf"{prefix}-(\d+)-.*\.md")
+    task_numbers = []
+
+    for filename in os.listdir(tasks_dir):
+        if filename == "archive":  # Skip archive directory
+            continue
+
+        match = task_pattern.match(filename)
+        if match:
+            task_numbers.append(int(match.group(1)))
+
+    if not task_numbers:
+        return f"{prefix}-01"
+
+    # Get next sequential number
+    next_num = max(task_numbers) + 1
+    return f"{prefix}-{next_num:02d}"
+
+if __name__ == "__main__":
+    # Support optional arguments
+    agent_dir = sys.argv[1] if len(sys.argv) > 1 else ".agent"
+    prefix = sys.argv[2] if len(sys.argv) > 2 else "TASK"
+
+    next_id = get_next_task_id(agent_dir, prefix)
+    print(next_id)