feat(agent): add canonical skill source

[derek-palmer]

Summary by CodeRabbit

• Documentation
  • Updated system specification to define canonical skill package source requirements and verification invariants for downstream packages
  • Added formal specification for skill activation triggers, context composition, workflow ordering, and safety constraints
  • Updated project roadmap status for skill distribution work from planned to in progress

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR establishes a canonical skill specification for the codeforerunner documentation/routing skill, documents how its post-frontmatter body must be preserved in downstream packaged implementations, updates the SPEC.md contract and P4 task references to reflect this preservation invariant, and marks the work as in progress on the roadmap.

Changes

Canonical Skill Specification and Contract

Layer / File(s)	Summary
Specification contract for canonical skill source SPEC.md	I.agent-skill is defined to point to agent/codeforerunner.skill.md with explicit guarantee that its post-frontmatter Markdown body is consumed verbatim by future skill packages. Invariant V10 reinforces that canonical skill-body preservation rule.
Canonical codeforerunner skill specification agent/codeforerunner.skill.md	New file defines the complete codeforerunner skill specification: activation triggers (doc generation, audits, stale checks, README/API/stack diagram updates), required repo inputs, layered prompt context composition, per-run workflow (scan then task prompt with output-contract handling), safety and scope constraints, naming conventions, and downstream packaging preservation rules.
P4 task and roadmap updates SPEC.md, docs/roadmap.md	P4 tasks T11–T15 expanded to include I.agent-skill and V10 citations. Roadmap P4: Skill/Plugin Distribution section status changed from "planned" to "in progress" with canonical skill source bullet reclassified as "Done".

Possibly related PRs

• derek-palmer/codeForerunner#9: Both PRs update the same SPEC.md contract for the P4 "skill/plugin distribution design" phase, with this PR further specifying the canonical I.agent-skill/V10 preservation rule and aligning P4 tasks to it.
• derek-palmer/codeForerunner#8: Both PRs update the same "skill/plugin distribution" documentation contracts in SPEC.md, with this PR establishing the canonical skill source and its downstream preservation invariant.

Poem

🐰 A skill takes form in markdown prose,
Preserved and cherished as it grows,
Contracts defined with V and I,
Where code and spec will never lie. 📜
The roadmap moves from planned to go—
One hop forward, watch it flow!

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'feat(agent): add canonical skill source' accurately and directly summarizes the primary change: introduction of agent/codeforerunner.skill.md as the canonical skill source. The title is concise, clear, and clearly conveys the main objective without extraneous details.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/canonical-skill-source

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/canonical-skill-source

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

agent/codeforerunner.skill.md (1)

16-19: 💤 Low value

Consider varying sentence structure for better readability.

Three consecutive bullets start with "Generate or refresh". While functionally clear, varying the phrasing slightly would improve flow. This is a minor style suggestion and can be safely deferred.

♻️ Optional rewording suggestion

 - Generate or refresh `README.md` from a repo's actual state.
-- Generate or refresh API documentation.
-- Generate or refresh stack / runtime / dependency documentation.
+- Update or create API documentation.
+- Refresh stack / runtime / dependency documentation.
 - Produce or refresh architecture or flow Mermaid diagrams.

🤖 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 `@agent/codeforerunner.skill.md` around lines 16 - 19, The three consecutive
bullets in agent/codeforerunner.skill.md all begin with "Generate or refresh",
which is repetitive; update the four bullets to vary sentence openings while
preserving meaning—e.g., keep "Generate or refresh README.md" for README.md,
change the API line to "Create or update API documentation," change the
stack/runtime line to "Document stack, runtime, and dependency details," and
change the diagram line to "Produce or update architecture or flow Mermaid
diagrams"—referencing the existing targets README.md, API documentation, stack /
runtime / dependency documentation, and Mermaid diagrams to locate and edit the
bullets.

🤖 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.

Nitpick comments:
In `@agent/codeforerunner.skill.md`:
- Around line 16-19: The three consecutive bullets in
agent/codeforerunner.skill.md all begin with "Generate or refresh", which is
repetitive; update the four bullets to vary sentence openings while preserving
meaning—e.g., keep "Generate or refresh README.md" for README.md, change the API
line to "Create or update API documentation," change the stack/runtime line to
"Document stack, runtime, and dependency details," and change the diagram line
to "Produce or update architecture or flow Mermaid diagrams"—referencing the
existing targets README.md, API documentation, stack / runtime / dependency
documentation, and Mermaid diagrams to locate and edit the bullets.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 220ef267-b6e6-465e-895a-07d748de70e5

📥 Commits

Reviewing files that changed from the base of the PR and between 9868e80 and a8de49d.

📒 Files selected for processing (3)

• SPEC.md
• agent/codeforerunner.skill.md
• docs/roadmap.md