feat(claude): /feature-spec slash command — structured handoff that feeds the encoding loop#115
Merged
Merged
Conversation
…handoff Closes the spec-capture gap in the encoding loop. Draws a tight handoff document — goal + acceptance + affected surfaces + auto-referenced CLAUDE.md constraints + scaffolding suggestions — then prompts the user to encode lessons after implementation. The spec itself is ephemeral (ships as a GitHub issue + PR description); the lessons + significant decisions are durable across the five encoding surfaces. Why this exists (the gap it closes): Spec Kit's /specify produces a per-feature spec as the source of truth that code is derived from. NextAurora's loop deliberately doesn't do that (most features are pattern-conforming and a per-feature spec would re-state what CLAUDE.md already covers). But the loop did have a real gap: no structured way to capture "what this new feature is" at the handoff between intent and implementation. /feature-spec fills that without adopting Spec Kit's whole methodology. Three-layer persistence model: 1. SPEC (ephemeral) - the command's output. Ships as GitHub issue body + PR description. Archives when the feature ships. Once shipped, the code is the artifact. 2. IMPLEMENTATION LESSONS (durable) - rules/patterns surfaced while building. Encoded across the five surfaces (CLAUDE.md, .coderabbit.yaml, architecture-reviewer agent, skills, docs+diagrams). This is what the existing Continuous Rule Encoding loop already handles. 3. ARCHITECTURAL DECISIONS (durable, browseable) - for significant features (new bounded context, new transport, new tenancy model), an ADR-style doc under docs/decisions/ or addition to docs/project-decisions.md. The command: - Asks 2-4 clarifying questions to lock in scope (service, endpoint shape, domain changes, external integrations) - Drafts the structured spec (Goal, Acceptance, Affects, Constraints from CLAUDE.md - auto-inferred and linked) - Significance-checks for ADR-worthiness - Outputs a GitHub issue body + optional ADR draft + /new-feature-slice scaffolding suggestions - Closes with a verbatim "encode lessons after shipping" prompt to keep the spec → code → encoding loop closed The command file itself is a paraphrase site (Constraints from CLAUDE.md section lists rules with their canonical references). Marked with the `See CLAUDE.md.` cross-reference convention so /check-rules audits the alignment and the PostToolUse hook surfaces it when CLAUDE.md changes. What this is NOT: - Not Spec Kit. Doesn't produce a plan or task list. - Not implementation planning - that's /new-feature-slice + writing code. - Not an auto-encoder - it proposes; the user decides. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
WalkthroughAdds a command guide at ChangesFeature-spec command guide
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/commands/feature-spec.md:
- Line 120: The relative link "../.github/ISSUE_TEMPLATE/work-item.yml" in
.claude/commands/feature-spec.md is incorrect and resolves to .claude/.github;
update that link to "../../.github/ISSUE_TEMPLATE/work-item.yml" so it points to
the repository root template. Locate the markdown line containing the exact
string "../.github/ISSUE_TEMPLATE/work-item.yml" and replace it with
"../../.github/ISSUE_TEMPLATE/work-item.yml".
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: f5320e62-437b-4a76-87cb-3d2949c87a2e
📒 Files selected for processing (1)
.claude/commands/feature-spec.md
CI broken-link audit caught: ../.github/ISSUE_TEMPLATE/work-item.yml from .claude/commands/feature-spec.md resolves to .claude/.github/... which doesn't exist. Needs ../../ to walk out of both commands/ and .claude/. The guard caught this on its first run against the new file, exactly as designed (catching relative-path drift in markdown is the whole point of the broken-link audit added in #112). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
emeraldleaf
added a commit
that referenced
this pull request
Jun 5, 2026
#116) Three doc sites had drift from the recent encoding-loop work: README.md (line 18 "Two AI reviewers" callout) - Old: lists only .claude/skills/ as what Claude Code reads - New: lists the full .claude/ folder (agents, skills, slash commands, hook scripts, hook + permission wiring) — the meta-layer that gets ported between projects - ADDED a new "Continuous Rule Encoding" callout right after, introducing the loop + 3-tier enforcement spectrum + lean-CLAUDE.md discipline (~300 lines, CI soft cap 400, hard fail 500) + the 5 encoding surfaces + cross-links to /feature-spec, /article-audit, /check-rules, /new-feature-slice, /sync-status. Points at docs/dev-loop.md for full mechanics and docs/dev-loop-scaffolding.svg for the scaffolding diagram. docs/dev-loop.md (Slash commands table) - Was missing /feature-spec (just landed in #115) and /article-audit (landed earlier this week) - Added both with their actual one-line descriptions docs/dev-loop.svg (rendered diagram people see on GitHub) - Stage 1 "PostToolUse" hooks list: added check-file-moves.sh (the hook added in #114 for git-mv/git-rm detection) - Stage 1 "Slash commands" list: added /feature-spec and /article-audit alongside the existing 3; shifted Agents/Skills/Secondary-reviewer positions down by 54px to make room - Encoding loop "Encode in:" footer: was 4 surfaces (CLAUDE.md + .coderabbit.yaml + arch-reviewer Pattern Checklist + skill), now 5 surfaces (added "docs + paired diagrams" as surface 5, shortened labels to fit). Title now reads "Encode in 1+ of 5 surfaces" to clarify the surface count What this is NOT: - Not a full dev-loop.svg regeneration — the SVG also has other minor staleness (CLAUDE.md size annotation "25 KB" is outdated since the trim; integration tests list only shows Catalog + Order while CI now runs 4 slices). Targeted surgery here, not a rewrite. Verification: - broken-link guard: exit 0 on the changed markdown files - All cross-references resolve Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds `/feature-spec` slash command. Closes the spec-capture gap in the encoding loop without adopting Spec Kit's per-feature ceremony.
When invoked with a feature description, the command:
Three-layer persistence model
Why not Spec Kit
Same reasoning as the prior CLAUDE.md edits: per-feature spec ceremony is too heavy when the canon already covers "how to build it correctly" for most features. This command produces just the handoff document — not a plan, not tasks, not regenerable source-of-truth.
For multi-stakeholder greenfield work, Spec Kit still earns its keep. This command is for the case where the bottleneck is "structured handoff between intent and implementation," not "figuring out what to build."
The command itself participates in the encoding loop
The "Constraints from CLAUDE.md" section is a paraphrase site. When CLAUDE.md changes, the constraints list may need updating. Marked with the `See CLAUDE.md.` cross-reference convention so:
This means the command itself gets continuously improved — same as every other paraphrase site.
What this is NOT
Verification
🤖 Generated with Claude Code
Summary by CodeRabbit