AgentSkillsCN

feature

端到端功能交付流程：GitHub Issue → 规范 → 工作树 → 实施 → PR。一个功能 = 一个Issue = 一个工作树 = 一个分支。全程通过GitHub实现完全可追溯。

SKILL.md
--- frontmatter
name: feature
description: >
  End-to-end feature delivery: GitHub issue → spec → worktree → implementation → PR.
  One feature = one issue = one worktree = one branch. Full traceability via GitHub.
user-invocable: true

/feature

End-to-end pipeline: GitHub Issue → Spec → Worktree → Implementation → PR.

Input: #42, 42, issue URL, or free-text description.

PHASE 0: RESUME CHECK

  1. •

    Parse input:

    • •Number or #N → ISSUE = N
    • •URL https://github.com/.../issues/N → extract N
    • •Free text → will create issue in Phase 1
  2. •

    Verify GitHub CLI auth:

    code
    gh auth status
    • •FAIL → ❌ Error: Run 'gh auth login' first.
  3. •

    If ISSUE exists, fetch it:

    code
    gh issue view ISSUE --json number,title,body,state
    • •Issue not found → ❌ Error: Issue #ISSUE not found.
    • •Issue closed → warn user, ask confirmation to proceed
  4. •

    Derive identifiers:

    • •SLUG = kebab-case of issue title, max 40 chars
    • •BRANCH = feat/ISSUE-SLUG (e.g. feat/42-add-notifications)
    • •REPO_ROOT = git rev-parse --show-toplevel
    • •WT_ROOT = REPO_ROOT/../.worktrees/BRANCH
  5. •

    Check if worktree already exists:

    code
    git worktree list | grep BRANCH
    • •EXISTS → Read WT_ROOT/.claude/memory/project-state.md → RESUME from pending phase
    • •NOT EXISTS → continue to Phase 1

PHASE 1: INTAKE

Case A — Free-text description (no issue number):

code
gh issue create --title "TITLE" --body "BODY"
  • •Capture the returned ISSUE number
  • •Derive SLUG, BRANCH, WT_ROOT from the new issue

Case B — Existing issue:

  • •Already have issue content from Phase 0

(No comment posted — session start info is included in the Spec comment.)

PHASE 2: SPEC

  1. •

    Invoke planner agent with context:

    • •Issue body (title + description)
    • •.claude/memory/architecture.md
    • •.claude/memory/decisions/DEC-*.md
    • •.claude/project.yml
  2. •

    Planner produces structured spec:

    • •Scope: 1-3 sentences describing the change
    • •Tasks: decomposed into waves (ordered groups)
    • •Files: to create/modify
    • •Test strategy: what to test and how
    • •Invariant check: which invariants are affected
  3. •

    Post spec as issue comment (Comment 1/3):

    code
    gh issue comment ISSUE --body "🚀 **Branch:** \`feat/ISSUE-SLUG\`

## Spec

### Scope
...

### Tasks
- Wave 1: ...
- Wave 2: ...

### Files
...

### Test Strategy
...
"
  4. •

    Write tasks to project-state.md with metadata:

    code
    skill: feature
issue: #ISSUE
branch: BRANCH
phase: execution

PHASE 3: WORKTREE SETUP

  1. •

    Sync local main with remote:

    code
    git fetch origin
git switch main && git merge --ff-only origin/main
    • •If merge fails (local has diverged) → ❌ Error: Local main has diverged from origin. Resolve manually.
  2. •

    Create worktree directory:

    code
    mkdir -p REPO_ROOT/../.worktrees
git worktree add WT_ROOT -b BRANCH origin/main
  3. •

    Copy state to worktree:

    code
    cp REPO_ROOT/.claude/memory/project-state.md WT_ROOT/.claude/memory/project-state.md
  4. •

    Initialize clean locks in worktree:

    • •Write empty WT_ROOT/.claude/memory/locks.md

(No comment posted — progress is tracked in the living progress comment.)

PHASE 4: EXECUTION (inside worktree)

ISOLATION RULE — MANDATORY

From this phase until Phase 5 completes:

  • •ALL reads and writes MUST use absolute paths under WT_ROOT
  • •NEVER read from REPO_ROOT — the main checkout is off-limits
  • •NEVER write to REPO_ROOT — no copying files back to main
  • •NEVER cd to REPO_ROOT — stay inside the worktree
  • •The worktree IS the project root. Treat WT_ROOT as if REPO_ROOT does not exist.

If an agent or skill tries to reference a path outside WT_ROOT → STOP and fix the path.

Execution

  • •Agents read config from: WT_ROOT/.claude/stack.yml, WT_ROOT/.claude/memory/architecture.md
  • •Bash commands: cd WT_ROOT && {command}
  • •State updates: WT_ROOT/.claude/memory/project-state.md

For each task [ ] in WT_ROOT/.claude/memory/project-state.md:

  1. •Builder agent implements + tests
  2. •PASS → mark [x], print ✅ [task_number] task_description
  3. •FAIL → retry (max 2 retries). 3rd failure → post blocker to issue, STOP:
    code
    gh issue comment ISSUE --body "🚫 Blocked: [task description]. Error: [details]"

After EVERY completed wave, run these 3 steps in order — NO EXCEPTIONS:

  1. •

    Commit:

    code
    cd WT_ROOT && git add -A && git commit -m "feat(SLUG): wave N — [summary]"
  2. •

    Post/update progress comment (Comment 2/3):

    code
    gh issue comment ISSUE --edit-last --body "## 📊 Progress
✅ Wave 1: [summary]
✅ Wave 2: [summary]
...
⏳ X/Y tasks complete"

    If --edit-last fails (first wave, no previous comment), use --body without --edit-last:

    code
    gh issue comment ISSUE --body "## 📊 Progress
✅ Wave 1: [summary]
⏳ X/Y tasks complete"
  3. •

    Every 3 tasks: compress context via /summarize-context

PHASE 5: INTEGRATION

  1. •

    Verify ALL tasks are [x] in WT_ROOT/.claude/memory/project-state.md

  2. •

    Run final validation (tests + build):

    • •Read WT_ROOT/.claude/stack.yml for validate command and exec_prefix
    • •Execute: cd WT_ROOT && {exec_prefix} {stack.commands.validate}
    • •If validate not defined, run {stack.commands.test} then {stack.commands.build}
    • •Build step catches SSR/runtime errors (missing providers, import errors, type mismatches)
    • •FAIL → create fix tasks, return to Phase 4
  3. •

    Push branch:

    code
    cd WT_ROOT && git push -u origin BRANCH
    • •Push rejected → cd WT_ROOT && git pull --rebase origin BRANCH, retry once
  4. •

    Create PR:

    code
    gh pr create --title "feat: ISSUE_TITLE" --body "Closes #ISSUE

## Summary
[spec scope from Phase 2]

## Changes
[list of files changed]

## Test plan
[test strategy from Phase 2]
" --head BRANCH --base main
  5. •

    (PR URL is included in the final summary comment — Phase 6.)

PHASE 6: CLEANUP

  1. •

    Archive state:

    code
    mkdir -p REPO_ROOT/.claude/memory/archive/
cp WT_ROOT/.claude/memory/project-state.md REPO_ROOT/.claude/memory/archive/feature-ISSUE-$(date +%Y%m%d).md
  2. •

    Post final summary to issue (Comment 3/3):

    code
    gh issue comment ISSUE --body "## ✅ Feature Complete

**PR:** PR_URL
**Branch:** \`BRANCH\`
**Tasks:** Y/Y complete

<details><summary>Changes</summary>

[list of files changed]

</details>

Ready for review."
  3. •

    DO NOT remove worktree — may need fixes post-review

  4. •

    Output: ✅ Feature #ISSUE delivered. PR: PR_URL

Error Handling

ErrorAction
gh auth status fails❌ Error: Run 'gh auth login' first.
Issue not found❌ Error: Issue #ISSUE not found.
Push rejectedgit pull --rebase origin BRANCH, retry once
Task fails 3xPost blocker comment to issue, STOP
Session interruptedNext /feature #ISSUE resumes automatically from pending phase
Worktree conflictscd WT_ROOT && git rebase origin/main, resolve conflicts

Resumability

When /feature #N is invoked and a worktree for that issue already exists:

  1. •Read WT_ROOT/.claude/memory/project-state.md
  2. •Parse metadata: skill, issue, branch, phase
  3. •Find first uncompleted task [ ]
  4. •Resume from the appropriate phase:
    • •All tasks [ ] and no spec → Phase 2
    • •Tasks exist but no worktree work started → Phase 4
    • •Some tasks [x], some [ ] → Phase 4 (continue)
    • •All tasks [x] → Phase 5

Conventions

  • •One feature = one issue = one worktree = one branch
  • •Branch naming: feat/ISSUE-SLUG
  • •Worktree location: REPO_ROOT/../.worktrees/feat/ISSUE-SLUG
  • •Commits inside worktree use conventional format: feat(SLUG): description
  • •All GitHub communication via gh CLI — no API tokens needed beyond gh auth