[!CAUTION] Scope boundary: This skill produces a plan, a decision record, GitHub issue(s), and integrates them into the Product Roadmap project with correct phase assignments. It does NOT write application code, create components, modify database schemas, run tests, create branches for implementation, or perform any build work. If the user asks to start building after the plan is approved, direct them to run

/build-feature <issue-number>

— do not begin implementation yourself.

• What the feature does (user-facing behavior)
• Who it is for (target users)
• Why it matters (business or product value)
• Constraints (time, technical, budget, dependencies)

gh issue view <number> --json title,body,labels,state,number

build-ready

/plan-feature

[!WARNING] Issue #<number> already has the

build-ready

label, which means

/plan-feature

has been run on it before. Re-running will create a new decision record and may create duplicate implementation issues.

• (a) Continue anyway (re-plan from scratch, e.g., if requirements changed significantly)
• (b) Stop and use the existing plan (run

  /build-feature <number>

  instead)

• XS or S estimated size (1-2 days of work)
• Touches 3 or fewer files with no architectural decisions
• No frontend changes (or trivial frontend changes)
• No database schema changes
• No new API endpoints (modifications to existing startup/config code are fine)
• Clear, unambiguous implementation — there is essentially one right way to do it

[!TIP] This issue looks small enough to skip the full

/plan-feature

council workflow. The scope is clear, the implementation is straightforward, and running two councils plus a decision record would add more overhead than value.

Recommended action: Add the

build-ready

label directly and run

/build-feature <number>

or

/build-api <number>

to implement.

• (a) Apply

  build-ready

  and stop (they'll run

  /build-feature

  or

  /build-api

  separately)
• (b) Continue with the full

  /plan-feature

  workflow anyway (e.g., if they want council input for precedent or policy reasons)

1. Add the

   build-ready

   label to the issue
2. Add a brief implementation context comment documenting any decisions made during triage (e.g., which approach to use, accepted values, files to modify)
3. Stop — do not proceed to Step 2 or beyond

• Problem validity: Is this solving the right problem? Could the user's stated problem be a symptom of a deeper issue?
• Solution fit: Is this the best solution, or is the user anchored on the first idea that came to mind? Present 1-2 alternative approaches if viable.
• Scope creep risk: Is the user asking for more than they need? What's the smallest thing that would validate the core hypothesis?
• Timing: Is this the right thing to build now, given the current state of the project? Are there prerequisites or dependencies that should come first?

• "What happens if [edge case]? Have you considered...?"
• "You mentioned X — but how does that interact with the existing Y?"
• "What's the user's current workaround? How painful is it really?"
• "What would you cut if this had to ship in half the time?"

• What's strong about the proposal (validate what works)
• What concerns you (risks, blind spots, over-engineering)
• What you'd change (concrete suggestions, not vague warnings)
• Alternative framing (if the problem could be solved differently)

.claude/councils/product-council.md

Model Selection: See the Model Selection section in README.md for mapping agent model specs to Task tool parameters.

• User Value: Does this solve a real user problem? Market fit?
• Priority: Is this the right thing to build now?
• Recommendations: Strategic considerations, positioning

• Lean Scope: What is the smallest version we can ship to get feedback?
• Speed to Feedback: How quickly can we get this in front of users?
• Feature Flag Strategy: Should this be prototyped behind a feature flag?
• Recommendations: How to ship faster and learn faster

• Design Quality: Brand consistency? UX intuitiveness?
• Accessibility: WCAG compliance requirements?
• Recommendations: Design approach, component needs

• Cost Analysis: Budget required? Infrastructure costs?
• ROI Potential: Expected return on investment?
• Recommendations: Cost optimizations or budget concerns

• Technical Feasibility: Can we build this? Complexity level?
• Architectural Fit: Does this align with the current tech stack?
• Recommendations: Technical constraints or alternative approaches

• Implementation Assessment: UX feasibility? Component complexity?
• User Experience: Implementation challenges?
• Recommendations: Frontend implementation approach

• Where do you agree with the council? Reinforce the strongest points.
• Where do you disagree? If a council member's assessment seems off, say so and explain why.
• What did the council miss? Identify blind spots — topics no member raised that matter.
• Groupthink check: If all members agree, play devil's advocate. What's the strongest argument against this feature?
• Refined recommendation: Based on both the council input and your own critical analysis from Step 2, give your honest recommendation — build as proposed, modify scope, defer, or reconsider entirely.

• MVP Scope: What ships in the first increment (1-2 weeks max). List specific user-facing capabilities.
• Future Iterations: What comes after MVP validation. List deferred capabilities.
• Feature Flag Strategy: Whether this should ship behind a flag, and the flag name.
• Success Metrics: How will we know this feature works? Define 2-3 measurable outcomes.

.claude/councils/feature-council.md

Model Selection: See the Model Selection section in README.md for mapping agent model specs to Task tool parameters.

• Architecture Fit: Does this align with system design?
• Complexity Assessment: Is this appropriately scoped?
• Recommendations: Architectural considerations, patterns to follow

• UI/UX Approach: Component structure, user interaction flow
• Design Integration: Tailwind/shadcn components needed? New or existing?
• Recommendations: Frontend implementation strategy

• API Design: Endpoints, contracts, data flow
• Database Changes: Schema modifications needed?
• Recommendations: Backend implementation strategy

/backend-development:api-design-principles

• Testing Strategy: Unit, integration, E2E approach
• Edge Cases: Scenarios to test, boundary conditions
• Recommendations: Quality gates and acceptance criteria

• Size: XS (1 day), S (2 days), M (3 days), L (5 days), or XL (8 days) in business days
• Dependencies: Which other issues must complete before this one can start
• Milestone: Which phase (M1-M5) the issue belongs to
• Schedule position: Where in the milestone's serial queue this issue falls, considering dependencies and existing scheduled items

• Implementation risks: What's the hardest part of this plan? Where are teams most likely to get stuck or underestimate effort?
• Sequencing concerns: Is the task breakdown in the right order? Are there hidden dependencies between frontend and backend work?
• Over-engineering check: Is the council proposing more infrastructure than this feature needs? Could we do less and still validate the hypothesis?
• Under-engineering check: Is anything missing that will bite us later — error handling, migration rollback, accessibility, performance?
• Honest assessment: Given everything discussed, rate your confidence that this plan will succeed as written (High / Medium / Low) and explain why.

docs/decisions/

docs/decisions/001-example-architecture-decision.md

• Date: Today's date
• Council: Product Council + Feature Council
• Status: Approved (after user approval)
• Question: The feature being evaluated
• Context: Current situation, requirements, constraints
• Council Votes: All votes from both Product and Feature councils
• Decision: Approved scope (MVP + future)
• Rationale Summary: Synthesized perspectives from all council members
• Action Items: Task breakdown with clear owners (frontend, backend, testing)
• Timeline: Target dates based on complexity
• Follow-up: When to revisit, what to validate post-launch
• References: Related issues, documentation, prior decisions

.claude/CLAUDE.md

• Metadata blocks must use bullet points (

  - **Key**: value

  ), never consecutive bold lines.
• Use GitHub alerts (

  > [!NOTE]

  ,

  > [!TIP]

  ,

  > [!IMPORTANT]

  ,

  > [!WARNING]

  ,

  > [!CAUTION]

  ) for callouts instead of bold/italic emphasis.
• Include a mermaid diagram when the decision involves multiple components, services, or data flows. Place it in the Context or Rationale Summary section to visualize the architecture.
• Use collapsible

  <details>

  sections for lengthy council evaluations if the record would otherwise exceed ~150 lines of votes.
• Use tables for structured comparisons (e.g., options considered with trade-offs).

/documentation-generation:architecture-decision-records

1. Create a feature branch from the latest

   origin/main

   following CONTRIBUTING.md conventions:
   bash

   git fetch origin main
   git checkout -b feature/<feature-slug> origin/main

2. Save the decision record:

   docs/decisions/NNN-<feature-slug>.md

3. Update the decisions index:
   Regenerate the Decisions table in

   docs/decisions/INDEX.md

   by scanning all decision files in the directory. For each file (excluding

   INDEX.md

   and

   001-example-architecture-decision.md

   ):
   • Read the heading to extract the decision number and title
   • Read the metadata block to extract Date, Council, Status
   • Derive 2-5 Key Topics (lowercase, comma-separated) from the decision's Question and Context sections
   Rebuild the full table in reverse chronological order (newest first). Do not modify any other section of INDEX.md (the intro, How to Use, or Related Resources sections remain static).
4. Update the master documentation index:
   If any new documents were created in

   docs/

   (including the decision record), verify that

   docs/INDEX.md

   reflects them. Decision records are covered by the

   decisions/INDEX.md

   entry already present, so no per-decision update is needed. However, if a new documentation file was added to

   docs/

   outside of

   decisions/

   (e.g., a new science document), add a row to the appropriate table in

   docs/INDEX.md

   .
5. Commit with:

   docs(council): document feature plan for <feature-name>

6. Run Prettier on all new/modified files before pushing:
   bash

   pnpm exec prettier --write <files>

   Stage and commit any formatting fixes separately:

   style: fix Prettier formatting in decision record and skill

7. Push the branch and create a PR for the decision record:
   bash

   git push -u origin feature/<feature-slug>
   
   gh pr create \
     --title "docs(council): add Decision NNN — <feature-name>" \
     --body "## Summary\n\n- Adds Decision NNN documenting the council-approved plan for <feature-name>\n- Product Council (<tally>) and Feature Council (<tally>) both approved\n- Implementation issues: #N, #N, ...\n\n## Test plan\n\n- [ ] Decision record renders correctly in GitHub markdown\n- [ ] Mermaid diagrams render (if any)\n- [ ] All cross-references to existing issues and docs are valid links\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)"

8. Watch CI until all checks pass:
   bash

   gh pr checks <pr-number> --watch

   If checks fail, read the failure logs, fix the issue, commit, push, and re-watch. Do not proceed to issue creation until CI is green.

   [!IMPORTANT] Every

   /plan-feature

   run that produces a decision record must submit a PR to get the record merged to main. The PR must pass CI before the planning step is considered complete. The decision record branch is also the feature branch that

   /build-feature

   will use for implementation.

• <Decision 1>
• <Decision 2>
• <Decision 3>

• Decision Record: Decision NNN (link becomes active after the planning PR merges to main)
• Feature Branch:

  feature/<slug>

• Implementation Issue: #<new-issue-number> (created in Step 9)

/plan-feature

Add the `build-ready` label to the source issue (it has now been fully planned):

```bash
gh label list | grep -q "build-ready" || gh label create "build-ready" --description "Planned by /plan-feature and ready for /build-feature" --color "0E8A16"
gh issue edit <number> --add-label "build-ready"

Set phase and milestone fields to match the implementation issues that will be created in the Issue Creation step

> [!NOTE]
> The source issue retains its original content as context. The comment provides a clear audit trail of what the councils decided and links to the detailed decision record. After the implementation issue is created in the Issue Creation step (Step 9), come back and edit this comment to include the implementation issue number.

1. Decision record completeness: Verify the decision record file exists and contains all required sections (Question, Context, Council Votes, Decision, Rationale Summary, Action Items, Timeline). If any section is missing, stop and add it before proceeding.
2. Council consensus: Scan both council vote sections for any "Block" votes. If a Block vote exists:

   [!WARNING] A council member voted to Block this feature. Creating an implementation issue with unresolved Block votes is unusual. Consider addressing the concern before proceeding.

   Ask the user whether to proceed or resolve the concern first.
3. Task breakdown present: Verify the Action Items section contains at least one task (checkbox line). If empty, stop and ask the user to define the implementation tasks.
4. Approval status: Verify the Decision section shows

   Status: Approved

   . If not approved, warn the user before proceeding.
5. Duplicate issue detection: Search existing open issues for potential duplicates or substantially overlapping work:
   bash

   gh issue list --state open --limit 200 --json number,title,labels

   Compare the planned issue title(s) and scope against existing issues. If a potential duplicate is found:

   [!WARNING] Potential duplicate detected: issue #N has a similar title/scope. Review the existing issue before creating a new one.

   Present the potential duplicate(s) to the user and ask whether to:
   • (a) Update the existing issue instead (add the planning context as a comment)
   • (b) Create a new issue anyway (if scope is genuinely different — explain why)
   • (c) Adjust the plan to avoid overlap
   Do NOT create issues that substantially duplicate existing work items.

[!IMPORTANT] GitHub issues are actionable work items derived from the decision record — they do NOT replace it. The decision record (Step 6) remains the authoritative project-level record of council evaluations, rationale, and architectural context. Issues reference the decision record and provide a task-oriented view for

/build-feature

to consume.

/build-feature

.github/ISSUE_TEMPLATE/feature-implementation.yml

• Product Council vote tally and key decisions
• Feature Council vote tally and architecture decisions
• Any dissenting opinions or conditions

<details>

/build-feature

[Decision NNN](docs/decisions/NNN-slug.md)

The implementation plan has N phases. Would you like:

1. A single issue with all phases as task groups
2. Separate issues per phase (cross-referenced)

AGENTS.md

1. Create the parent issue first (high-level feature description, no implementation details)
2. Create child issues for each phase
3. Link children to parent via the sub-issues API:
   bash

   CHILD_ID=$(gh api repos/{OWNER}/{REPO}/issues/<child-number> --jq '.id')
   gh api repos/{OWNER}/{REPO}/issues/<parent-number>/sub_issues -X POST -F sub_issue_id=$CHILD_ID

4. Set the parent issue's dates to span all children (earliest Start to latest Target)
5. If children span multiple milestones: Remove the parent from any milestone (

   gh api repos/{OWNER}/{REPO}/issues/<number> -X PATCH -F milestone=null

   ) and clear its project phase field via GraphQL (

   clearProjectV2ItemFieldValue

   ). The parent is a tracking container; children carry milestone and phase assignments. If a source issue was used as the parent and already had a milestone, remove it.

1. Review existing phases on the {PROJECT_BOARD_NAME}: <!-- TODO: Replace {PROJECT_BOARD_NAME} with your project board's display name -->
   bash

   gh project field-list 6 --owner {OWNER} --format json

2. Map each issue to a phase based on the milestone breakdown in

   docs/PRODUCT.md

   and the nature of the work. Consider where the issue fits in the existing roadmap progression.
3. Recommend new phases if the planned work doesn't fit any existing phase. New phase recommendations must include a rationale and where they sit relative to existing phases (e.g., "between M2 and M3").

/build-feature

• Add

  build-ready

  if the issue has a concrete task breakdown, clear acceptance criteria, and no significant open questions. This is the common case for single-issue plans and for well-scoped child issues in multi-issue plans.
• Do NOT add

  build-ready

  if the issue is broad, has open architectural questions, or would benefit from its own

  /plan-feature

  pass to refine scope and get council input. This is common for large child issues in multi-issue plans where only the high-level direction was established.

undefined

AGENTS.md

1. Check the existing schedule in the target milestone:
   bash

   gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200

   Find the latest Target date of any non-gate item in the milestone. Gate items are issues labeled

   gtm-review

   or

   security-audit

   — exclude them when determining the insertion point.
2. Compute the new issue's dates using the size-to-days table (XS=1, S=2, M=3, L=5, XL=8 business days). The Start date is the next business day after the latest non-gate item's Target (or after the dependency's Target, whichever is later). Skip weekends.
3. Cascade all subsequent items. After inserting the new issue, recompute the Start and Target dates of every issue that follows it in the milestone. Each subsequent issue's Start = next business day after the previous issue's Target. There must be no gaps or overlaps between consecutive issues — Start and Target dates determine the order of operations.
4. Shift gate items forward. Every milestone must end with exactly two gate items in this fixed order: GTM review (second-to-last), then security audit (last). After all non-gate items are positioned, recompute the gate items' dates so the GTM review starts the next business day after the last non-gate item's Target, and the security audit starts the next business day after the GTM review's Target. Update both gate items' Start and Target dates on the project board.
5. Update the milestone due date if the security audit's new Target extends it:
   bash

   gh api repos/{OWNER}/{REPO}/milestones/<number> -X PATCH -f due_on="<new-target>T00:00:00Z"

   [!IMPORTANT] No issue of any kind (feature, bug fix, chore, test, etc.) may ever be scheduled after the GTM review and security audit gate items. These two items are always the final items in every milestone, and their order (GTM → security audit) is an invariant that must be preserved on every project update.

6. Update all affected items on the project board using the Start and Target field IDs. Only recompute the current milestone being developed. Later milestones will be adjusted when the current milestone ends.

1. Check for existing GTM review issues in affected phases:
   bash

   gh issue list --state open --label "gtm-review" --json number,title

2. For phases missing a GTM review issue, create one:
   bash

   gh issue create \
     --title "gtm: Go to Market & Business Review — <Phase Name>" \
     --body "<body>" \
     --label "enhancement" \
     --label "marketing" \
     --label "gtm-review"

   The GTM review issue body must include:
   • Phase Summary: Features and changes included in this phase
   • Marketing Page Audit: Checklist to verify landing pages, feature descriptions, screenshots, and CTAs reflect the phase's changes
   • Content Consistency: Blog posts, help docs, and in-app copy alignment with new capabilities
   • GTM Recommendations: Positioning, messaging, launch tactics, and channel strategy
   • Business Review: Revenue impact, pricing implications, competitive positioning updates
   • Success Metrics: How to measure GTM effectiveness for this phase

   [!IMPORTANT] All user-facing copy produced during GTM work (landing pages, blog posts, in-app text, marketing content) must follow the User-Facing Content Style rules in

   AGENTS.md

   . No em dashes, no AI-slop vocabulary, no promotional inflation.

   Add the GTM review issue to the project with the correct phase, size, milestone, and dates:
   bash

   GTM_URL=<created-issue-url>
   GTM_NUM=$(echo "$GTM_URL" | grep -o '[0-9]*$')
   
   # Add to project and set fields
   GTM_ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "$GTM_URL" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {PHASE_FIELD_ID} --single-select-option-id <phase-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {SIZE_FIELD_ID} --single-select-option-id <size-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {START_FIELD_ID} --date <start-date>
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {TARGET_FIELD_ID} --date <target-date>

   The GTM issue is S (2 business days). Its Start date is the next business day after the last feature issue's Target in the phase. Compute dates using the same schedule logic as feature issues (see Schedule Date Computation above).
3. For phases that already have a GTM review issue, check whether the newly planned work is covered. If the phase scope has expanded significantly, add a comment to the existing GTM issue noting the new items that need review.

[!IMPORTANT] GTM review issues ensure that every shippable phase includes a business review checkpoint. They are not optional — every phase must have one before the phase is considered complete. Exemption: Phases that are purely bug fixes or continuous delivery/maintenance (e.g., dependency upgrades, security patches, CI improvements) are exempt.

1. Check for existing security audit issues in affected phases:
   bash

   gh issue list --state open --label "security-audit" --json number,title

2. For phases missing a security audit issue, create one:
   bash

   gh issue create \
     --title "security: Comprehensive Security Audit — <Phase Name>" \
     --body "<body>" \
     --label "enhancement" \
     --label "security-audit"

   The security audit issue body must include:
   • Phase Summary: Features, services, and changes included in this phase that require security review
   • Audit Scope: Which areas of the codebase are affected (API endpoints, authentication flows, data models, third-party integrations, etc.)
   • SAST Scanning: Run automated static analysis on all code changes in the phase
   • STRIDE Threat Modeling: Apply STRIDE methodology to new or modified features
   • Attack Tree Analysis: Build attack trees for the top 3 risks identified in threat modeling
   • Dependency Audit: Review new or updated dependencies for known vulnerabilities
   • Remediation Plan: Prioritized list of findings with severity ratings and fix recommendations
   Add the security audit issue to the project with the correct phase, size, milestone, and dates:
   bash

   SEC_URL=<created-issue-url>
   SEC_NUM=$(echo "$SEC_URL" | grep -o '[0-9]*$')
   
   # Add to project and set fields
   SEC_ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "$SEC_URL" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {PHASE_FIELD_ID} --single-select-option-id <phase-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {SIZE_FIELD_ID} --single-select-option-id <size-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {START_FIELD_ID} --date <start-date>
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {TARGET_FIELD_ID} --date <target-date>

   The security audit issue is M (3 business days). Its Start date is the next business day after the GTM issue's Target in the same phase. The security audit is always the last issue in a phase. Compute dates using the same schedule logic as feature issues (see Schedule Date Computation above).
3. For phases that already have a security audit issue, check whether the newly planned work is covered. If the phase scope has expanded significantly, add a comment to the existing security audit issue noting the new items that need review.

[!IMPORTANT] Security audit issues ensure that every shippable phase includes a security checkpoint before release. They are not optional — every phase must have one before the phase is considered complete. The security audit is always the last issue in a phase, running after the GTM review. Run it using

/security-audit

. Exemption: Phases that are purely bug fixes or continuous delivery/maintenance (e.g., dependency upgrades, security patches, CI improvements) are exempt — same as the GTM review exemption.

• Approved Scope: MVP capabilities and deferred items
• Task Breakdown: Frontend, backend, database, and testing tasks
• Feature Flag: Name and strategy (if applicable)
• Success Metrics: How we'll measure outcomes
• Branch: Feature branch name ready for implementation
• Decision Record: File path for reference
• GitHub Issue(s): Issue number(s) and URL(s) for the implementation plan
• Project Phase(s): Which phase(s) on the Product Roadmap each issue is assigned to
• GTM Coverage: GTM review issue(s) for affected phase(s) — created, updated, or verified
• Security Audit Coverage: Security audit issue(s) for affected phase(s) — created, updated, or verified

/build-feature <issue-number>

/build-api