aped-method 1.9.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aped-method",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Scaffold the APED pipeline (Analyze, PRD, Epics, Dev, Review) into any Claude Code project",
   "bin": {

package/src/templates/references.js

@@ -66,6 +66,10 @@ export function references(c) {
       path: `${a}/aped-qa/references/test-patterns.md`,
       content: TEST_PATTERNS,
     },
+    {
+      path: `${a}/aped-d/references/ticket-git-workflow.md`,
+      content: TICKET_GIT_WORKFLOW,
+    },
   ];
 }
 
@@ -1111,3 +1115,192 @@ describe("{Endpoint/Service}", () => {
 - **Testing implementation**: Test behavior, not internal structure.
 - **No assertions**: Every test must assert something. \`expect(true).toBe(true)\` is not a test.
 `;
+
+const TICKET_GIT_WORKFLOW = `# Ticket System & Git Provider Integration
+
+Read \`ticket_system\` and \`git_provider\` from config.yaml to adapt all instructions below.
+
+---
+
+## Ticket System Sync Rules
+
+### If ticket_system = "none"
+Skip all ticket references. Use plain commit messages without ticket IDs.
+
+### If ticket_system = "linear"
+
+**BEFORE starting a story:**
+1. Find the corresponding Linear issue
+2. Move issue status to **In Progress**
+3. Use the **Linear-suggested git branch name** (from Linear UI: "Copy git branch name")
+4. Add a comment on the issue: what you're about to implement
+
+**DURING development:**
+- Reference the Linear issue ID in EVERY commit message
+- Use **Linear magic words** for auto-linking:
+  - \`Part of TEAM-XX\` — links without closing (use in intermediate commits)
+  - \`Fixes TEAM-XX\` — links and auto-closes issue on merge
+- Commit format: \`type(TEAM-XX): description\\n\\nPart of TEAM-XX\`
+
+**AFTER completing:**
+1. Create PR with issue ID: \`gh pr create --title "feat(TEAM-XX): Story X.Y - Description" --body "Fixes TEAM-XX"\`
+2. Move issue to **In Review**
+3. After merge: move to **Done**
+4. Update state.yaml to match
+
+### If ticket_system = "jira"
+
+**BEFORE:** Find JIRA issue (PROJ-XX), move to In Progress, use branch: \`feature/PROJ-XX-description\`
+
+**DURING:**
+- Reference JIRA issue ID in every commit: \`type(PROJ-XX): description\`
+- JIRA smart commits: \`PROJ-XX #in-progress\`, \`PROJ-XX #done\`
+
+**AFTER:**
+- PR title: \`feat(PROJ-XX): Story X.Y - Description\`
+- JIRA auto-links PRs via issue ID in branch name or commit
+
+### If ticket_system = "github-issues"
+
+**BEFORE:** Find GitHub issue #XX, assign yourself
+
+**DURING:**
+- Reference in commits: \`type(#XX): description\`
+- Use \`Closes #XX\` or \`Fixes #XX\` in final commit/PR body
+
+**AFTER:**
+- \`gh pr create --title "feat: Story X.Y" --body "Closes #XX"\`
+- Issue auto-closes when PR merges
+
+### If ticket_system = "gitlab-issues"
+
+**BEFORE:** Find GitLab issue #XX, assign yourself
+
+**DURING:**
+- Reference: \`type(#XX): description\`
+- Use \`Closes #XX\` in commit/MR body
+
+**AFTER:**
+- \`glab mr create --title "feat: Story X.Y" --description "Closes #XX"\`
+- Issue auto-closes when MR merges
+
+---
+
+## Git Provider Workflow
+
+### If git_provider = "github"
+
+**Branch strategy:**
+\`\`\`
+main (production)
+  └── develop (integration, if configured)
+        └── feature/{ticket-id}-description
+\`\`\`
+
+**Commands:**
+\`\`\`bash
+# Start story
+git checkout main  # or develop if exists
+git pull
+git checkout -b feature/{ticket-id}-description
+
+# During dev
+git add <specific-files>  # NEVER git add . or git add -A
+git commit -m "type({ticket-id}): description"
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+gh pr create --base main --title "type({ticket-id}): Story X.Y - Title" --body "Fixes {ticket-id}"
+
+# After merge
+git checkout main && git pull
+git branch -d feature/{ticket-id}-description
+\`\`\`
+
+### If git_provider = "gitlab"
+
+**Commands:**
+\`\`\`bash
+# Start
+git checkout main && git pull
+git checkout -b feature/{ticket-id}-description
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+glab mr create --base main --title "type({ticket-id}): Story X.Y" --description "Closes {ticket-id}"
+
+# After merge
+git checkout main && git pull
+git branch -d feature/{ticket-id}-description
+\`\`\`
+
+### If git_provider = "bitbucket"
+
+**Commands:**
+\`\`\`bash
+# Start
+git checkout main && git pull
+git checkout -b feature/{ticket-id}-description
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+# Create PR via Bitbucket web UI or API
+\`\`\`
+
+---
+
+## Commit Message Format
+
+\`\`\`
+type({ticket-id}): short description
+
+[Optional body]
+
+{Magic word} {ticket-id}
+\`\`\`
+
+| Prefix | Usage |
+|--------|-------|
+| feat | New feature / story implementation |
+| fix | Bug fix |
+| refactor | Code restructuring (no behavior change) |
+| test | Adding or updating tests |
+| docs | Documentation changes |
+| chore | Build, config, tooling changes |
+
+---
+
+## State Sync
+
+Local state.yaml and ticket system MUST agree:
+
+| state.yaml | Linear | Jira | GitHub/GitLab Issues |
+|------------|--------|------|---------------------|
+| backlog | Backlog | Backlog | No label |
+| ready-for-dev | Todo | To Do | "ready" label |
+| in-progress | In Progress | In Progress | "in progress" label |
+| review | In Review | In Review | PR linked |
+| done | Done | Done | Closed |
+
+**If they diverge, the ticket system is the authority.** Update state.yaml to match.
+
+---
+
+## Epic/Milestone Tracking
+
+- When first story of an epic moves to In Progress → update epic/milestone status
+- When ALL stories in an epic are Done → mark milestone complete
+- Keep milestone descriptions updated if scope changes
+
+---
+
+## Critical Rules
+
+1. NEVER commit directly to main
+2. ALWAYS create feature branch before starting
+3. ALWAYS include ticket ID in every commit message
+4. ALWAYS update ticket status: In Progress → In Review → Done
+5. ALWAYS stage specific files — never \`git add .\` or \`git add -A\`
+6. ALWAYS use ticket system's suggested branch name when available
+7. NEVER commit secrets (.env, API keys, settings.local.json)
+`;

package/src/templates/skills.js

@@ -335,13 +335,18 @@ Story files: \`${o}/stories/{story-key}.md\`
 
 ## Ticket System Integration
 
-Read \`ticket_system\` from config. If not \`none\`:
+Read \`ticket_system\` from config. Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full guide.
+
+If \`ticket_system\` is not \`none\`:
 - Add ticket reference in each story header: \`**Ticket:** {{ticket_id}}\`
-- If \`jira\`: format as \`PROJ-###\` placeholder
-- If \`linear\`: format as \`TEAM-###\` placeholder
-- If \`github-issues\`: format as \`#issue_number\` placeholder
-- If \`gitlab-issues\`: format as \`#issue_number\` placeholder
+- Add suggested branch name: \`**Branch:** feature/{{ticket_id}}-{{story-slug}}\`
+- Format ticket ID per provider:
+  - \`linear\`: \`TEAM-###\` (e.g., \`KON-10\`)
+  - \`jira\`: \`PROJ-###\` (e.g., \`PROJ-42\`)
+  - \`github-issues\`: \`#issue_number\` (e.g., \`#10\`)
+  - \`gitlab-issues\`: \`#issue_number\` (e.g., \`#10\`)
 - Note: actual ticket creation is manual — these are reference placeholders
+- In Dev Notes, add: "Commit prefix: \`feat({{ticket_id}})\`"
 
 ## FR Coverage Map
 
@@ -469,11 +474,32 @@ Mark \`[x]\` ONLY when: tests exist, pass 100%, implementation matches, ACs sati
 
 **STOP and ask user if:** new dependency, 3 consecutive failures, missing config, ambiguity.
 
-## Git Commit Convention
+## Git & Ticket Workflow
+
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full integration guide.
+
+Read \`ticket_system\` and \`git_provider\` from \`${a}/config.yaml\`.
+
+### Before Implementation
+If \`ticket_system\` is not \`none\`:
+1. Find the corresponding ticket/issue for this story
+2. Move ticket status to **In Progress**
+3. Create feature branch using ticket system's suggested name
+4. Add a comment on the ticket: implementation plan
+
+If \`ticket_system\` is \`none\`:
+1. Create branch: \`feature/{story-key}\`
 
-Read \`git_provider\` and \`ticket_system\` from config:
-- Commit message format: \`type(scope): description\`
-- If ticket system configured, append ticket ref: \`type(scope): description [TICKET-ID]\`
+### During Implementation
+- Include ticket ID in EVERY commit: \`type({ticket-id}): description\`
+- Use magic words for auto-linking (see reference doc)
+- NEVER use \`git add .\` — stage specific files only
+
+### After Implementation
+1. Push branch and create PR/MR (adapt to \`git_provider\`):
+   - \`github\`: \`gh pr create --title "feat({ticket-id}): Story X.Y" --body "Fixes {ticket-id}"\`
+   - \`gitlab\`: \`glab mr create --title "feat({ticket-id}): Story X.Y" --description "Closes {ticket-id}"\`
+2. Move ticket to **In Review**
 
 ## Completion
 
@@ -572,6 +598,20 @@ Severity: CRITICAL > HIGH > MEDIUM > LOW. Format: \`[Severity] Description [file
 - MEDIUM/LOW only: fix automatically, story — \`done\`
 - HIGH+: fix or add \`[AI-Review]\` items, story — \`in-progress\`
 
+## Ticket & Git Update
+
+Read \`ticket_system\` and \`git_provider\` from \`${a}/config.yaml\`.
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for details.
+
+If story → \`done\`:
+1. If PR exists: approve/merge (adapt to \`git_provider\`)
+2. If \`ticket_system\` is not \`none\`: move ticket to **Done**
+3. Cleanup: delete feature branch after merge
+
+If story → \`in-progress\` (review found HIGH+ issues):
+1. Add [AI-Review] items as comments on the PR
+2. Ticket stays in **In Review**
+
 ## State Update
 
 Update \`${o}/state.yaml\`. If more stories remain: invoke Skill tool with \`skill: "aped-d"\`. If all stories done: report pipeline completion.
@@ -966,11 +1006,20 @@ Based on current state, suggest the next logical command:
 - If all stories \`done\`: suggest pipeline complete
 - If blockers found: describe resolution path
 
-## Ticket System Integration
+## Ticket System Sync
+
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for status mapping.
 
 If \`ticket_system\` is not \`none\`:
-- Show ticket references alongside story statuses
-- Note any stories without ticket references
+- Show ticket ID alongside each story status
+- Flag any stories without ticket references
+- Check sync: compare state.yaml statuses with expected ticket statuses
+- If divergence detected: warn user — "state.yaml says X, ticket system should be Y"
+- Display mapping table:
+  - \`backlog\` → Backlog/Todo
+  - \`in-progress\` → In Progress
+  - \`review\` → In Review
+  - \`done\` → Done
 
 ## Output
 
@@ -1402,13 +1451,18 @@ Quick checklist — no full adversarial review:
 - [ ] No regressions in existing tests
 - [ ] AC from quick spec satisfied
 
-## Git Commit
+## Git & Ticket Workflow
 
 Read \`ticket_system\` and \`git_provider\` from config.
-- Format: \`type(scope): description\`
-- Append ticket ref if configured
-- If \`git_provider\` is \`github\`: suggest PR creation with \`gh pr create\`
-- If \`git_provider\` is \`gitlab\`: suggest MR creation with \`glab mr create\`
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full guide.
+
+1. **Branch**: create \`fix/{ticket-id}-{slug}\` or \`feature/{ticket-id}-{slug}\`
+2. **Commits**: \`type({ticket-id}): description\` — include magic words per ticket provider
+3. **PR/MR**:
+   - \`github\`: \`gh pr create --title "fix({ticket-id}): description" --body "Fixes {ticket-id}"\`
+   - \`gitlab\`: \`glab mr create --title "fix({ticket-id}): description" --description "Closes {ticket-id}"\`
+   - \`bitbucket\`: push branch, create PR via web
+4. **Ticket**: move to Done after merge
 
 ## Output