Repository navigation
feat(assets): scaffold the six knowledge-base skills and their commands - #3
Merged
Merged
Conversation
`scc init` shipped eight validators and no skill teaching the formats they enforce, so a fresh workspace demanded conformance to documents nobody was told how to write. design/plan.md recorded this as an open deviation: the design listed skills among what the binary scaffolds and never said which, which left 3.3 and 6.3 satisfiable by a workspace containing no skills. Which skills ship is now picked mechanically — one per docs/ artifact a validator checks (wiki, codewiki, glossary, stack, adr), plus prd as the entry point for work too large for one spec. Each ships with a namespaced slash command derived from the same list, so the two cannot drift. The methodology stays in .claude/rules/. csdd shipped tdd-cycle, unit-cycle and verify-change as skills; here that would be a second copy of a rule, and the copy is the one that goes stale. Skills carry the procedure and the judgment, the format stays in knowledge-base.md, stated once. Commands are prefixed scc- because slash commands share a flat namespace across every source Claude Code loads them from, and a bare /adr collides on contact. Skills are not prefixed: a skill is reached through its description. TestScaffoldedSkillsPassTheSkillValidator asserts the scaffolded count before it asserts the clean run, which is the part that was missing while 6.3 was hollow. Template version bumped to 2. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01K2uD2SD6syaoXnhtqHbzhM
📝 WalkthroughWalkthrough
ChangesKnowledge skill scaffolding
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant Developer
participant Init as init
participant Assets as assets.Workspace
participant Validator as skill validator
Developer->>Init: initialize workspace
Init->>Assets: scaffold configured skills and commands
Assets-->>Init: write embedded templates
Developer->>Validator: validate scaffolded skills
Validator-->>Developer: return validation result
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@internal/assets/templates/claude/commands/scc-codewiki.md`:
- Line 3: Update the command instructions around the argument handling to
recognize the exact “repair” argument explicitly and route it through the
existing codewiki.* repair workflow, instead of treating it as an area and
skipping repair. Keep normal area/path narration behavior unchanged;
alternatively remove “repair” from the argument hint if repair mode is not
intended to be supported.
In `@internal/assets/templates/claude/skills/prd/SKILL.md`:
- Around line 49-51: Update the fenced command block containing “scc plan new
<name>” in the PRD skill template to declare the shell language, preserving the
command content and formatting while satisfying markdownlint MD040.
In `@internal/assets/templates/claude/skills/wiki/SKILL.md`:
- Around line 30-37: Update the raw-source handling procedure in the wiki skill
so deleting files from docs/raw/ requires explicit user confirmation before the
irreversible deletion; otherwise archive the source instead. Preserve the
requirement to record the outcome in changelog.md and run scc validate,
including for sources rejected as not worth a page.
🪄 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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 736cbbd0-bbe7-46d2-8849-078f616ef0cd
📒 Files selected for processing (21)
CLAUDE.mddesign/orchestration.mddesign/plan.mdinternal/assets/assets.gointernal/assets/assets_test.gointernal/assets/templates/CLAUDE.mdinternal/assets/templates/claude/commands/scc-adr.mdinternal/assets/templates/claude/commands/scc-codewiki.mdinternal/assets/templates/claude/commands/scc-glossary.mdinternal/assets/templates/claude/commands/scc-prd.mdinternal/assets/templates/claude/commands/scc-stack.mdinternal/assets/templates/claude/commands/scc-wiki.mdinternal/assets/templates/claude/skills/adr/SKILL.mdinternal/assets/templates/claude/skills/codewiki/SKILL.mdinternal/assets/templates/claude/skills/glossary/SKILL.mdinternal/assets/templates/claude/skills/prd/SKILL.mdinternal/assets/templates/claude/skills/stack/SKILL.mdinternal/assets/templates/claude/skills/wiki/SKILL.mdinternal/cli/cli.gointernal/cli/init.gointernal/cli/validate_test.go
| @@ -0,0 +1,13 @@ | |||
| --- | |||
| description: Narrate an area of the codebase into docs/codewiki/, every section citing the exact lines it explains | |||
| argument-hint: [area or path to narrate | repair] | |||
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Handle the documented repair mode explicitly.
The argument hint advertises repair, but the instructions only run validation when $ARGUMENTS is empty. /scc-codewiki repair therefore sets Area: repair and skips the codewiki.* repair workflow. Branch on the exact repair argument, or remove it from the argument hint.
Also applies to: 10-13
🤖 Prompt for 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.
In `@internal/assets/templates/claude/commands/scc-codewiki.md` at line 3, Update
the command instructions around the argument handling to recognize the exact
“repair” argument explicitly and route it through the existing codewiki.* repair
workflow, instead of treating it as an area and skipping repair. Keep normal
area/path narration behavior unchanged; alternatively remove “repair” from the
argument hint if repair mode is not intended to be supported.
Comment on lines
+49
to
+51
| ``` | ||
| scc plan new <name> | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language to the fenced command block.
markdownlint reports MD040 here. Mark the block as shell so the template remains lint-clean.
Proposed fix
-```
+```shell📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` | |
| scc plan new <name> | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 49-49: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for 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.
In `@internal/assets/templates/claude/skills/prd/SKILL.md` around lines 49 - 51,
Update the fenced command block containing “scc plan new <name>” in the PRD
skill template to declare the shell language, preserving the command content and
formatting while satisfying markdownlint MD040.
Source: Linters/SAST tools
Comment on lines
+30
to
+37
| 6. **Record it in `changelog.md`** — what changed, naming the pages with wikilinks. | ||
| 7. **Delete the source from `docs/raw/`.** This is the step that gets skipped. The | ||
| finding exists because of it. | ||
| 8. `scc validate` before you call it done. | ||
|
|
||
| A source that turns out not to be worth a page still gets deleted. "Read and | ||
| rejected" is a complete outcome; leaving the file behind pretends the work is | ||
| pending. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Require confirmation before deleting raw sources.
This procedure authorizes irreversible deletion of docs/raw/ input—and does so before scc validate. Require explicit user confirmation, or archive the source, before deleting it.
Proposed ordering
6. **Record it in `changelog.md`** — what changed, naming the pages with wikilinks.
-7. **Delete the source from `docs/raw/`.** This is the step that gets skipped. The
- finding exists because of it.
-8. `scc validate` before you call it done.
+7. `scc validate` before you call it done.
+8. Ask the user to confirm deletion, then remove the source from `docs/raw/`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 6. **Record it in `changelog.md`** — what changed, naming the pages with wikilinks. | |
| 7. **Delete the source from `docs/raw/`.** This is the step that gets skipped. The | |
| finding exists because of it. | |
| 8. `scc validate` before you call it done. | |
| A source that turns out not to be worth a page still gets deleted. "Read and | |
| rejected" is a complete outcome; leaving the file behind pretends the work is | |
| pending. | |
| 6. **Record it in `changelog.md`** — what changed, naming the pages with wikilinks. | |
| 7. `scc validate` before you call it done. | |
| 8. Ask the user to confirm deletion, then remove the source from `docs/raw/`. | |
| A source that turns out not to be worth a page still gets deleted. "Read and | |
| rejected" is a complete outcome; leaving the file behind pretends the work is | |
| pending. |
🧰 Tools
🪛 SkillSpector (2.4.4)
[warning] 71: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.
Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.
(Excessive Agency (EA2))
🤖 Prompt for 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.
In `@internal/assets/templates/claude/skills/wiki/SKILL.md` around lines 30 - 37,
Update the raw-source handling procedure in the wiki skill so deleting files
from docs/raw/ requires explicit user confirmation before the irreversible
deletion; otherwise archive the source instead. Preserve the requirement to
record the outcome in changelog.md and run scc validate, including for sources
rejected as not worth a page.
Source: Linters/SAST tools
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.
The gap
scc initscaffolded eight validators and no skill teaching the formats they enforce. A fresh workspace demanded conformance todocs/wiki/,docs/codewiki/,docs/glossary.md,docs/stack.mdanddocs/adr/while offering nothing that says how to write any of them.This was a known, recorded deviation rather than a regression —
design/plan.md:This PR writes that line and the skills behind it.
What ships
The selection rule is mechanical: one skill per
docs/artifact a validator checks, plus one entry point.wiki/scc-wikidocs/wiki/— ingest fromraw/, query, repairwikicodewiki/scc-codewikidocs/codewiki/— narrated code, cited by line rangecodewikiglossary/scc-glossarydocs/glossary.mdglossarystack/scc-stackdocs/stack.mdstackadr/scc-adrdocs/adr/adrprd/scc-prdplans/<name>.mdplanFive pair 1:1 with a validator of the same name.
prdis the exception and earns its place for the opposite reason: it is the on-ramp for work too large for one spec, the one place §1's routing question gets asked out loud.Decisions
tdd-cycle,unit-cycle,verify-changeandpr-review; here those are already rules under.claude/rules/. A skill restating a rule is a second copy of one fact, and the copy is the one that goes stale.knowledge-base.md, stated once. Skills link to it rather than restating it.scc-, skills are not. Slash commands share a flat namespace across every source Claude Code loads them from, and a bare/adrcollides on contact. A skill is reached through itsdescription, where a prefix only spends name budget.assets.KnowledgeSkillsderives both the skill directory and its command, so they cannot drift apart.Verification
gofmt -lclean,go vet ./...clean, full suite green.initwrites 24 files,scc skill validate→ 0 findings,scc validate→ 0 across all eight, re-runninginitis a no-op.TestScaffoldedSkillsPassTheSkillValidatorasserts the scaffolded count before it asserts the clean run — that is what was missing while 6.3 was hollow, since the old assertion passed on a workspace with zero skills.TestEverySkillShipsWithItsCommandholds the derivation honest in both directions.design/orchestration.md§6 now names the six and why;plan.md3.3 and 6.3 are checked and no longer vacuous.assets.Versionbumped1→2.Notes for the reviewer
golangci-lintandgovulncheckwere not run locally (not installed on this machine) — CI covers them. The Go change is confined toassets.goand tests.scc updatestill does not exist, so existing workspaces get these by re-runninginit, which is additive and never overwrites an edited file. Side effect worth noting: this is the first time a second template version exists, which was the stated blocker on phase 11.🤖 Generated with Claude Code
https://claude.ai/code/session_01K2uD2SD6syaoXnhtqHbzhM
Summary by CodeRabbit
New Features
initnow scaffolds six knowledge-base skills: wiki, codewiki, glossary, stack, ADR, and PRD.scc-slash commands for each skill.Documentation
Tests