add learn and rule skills, optimize all skills for token efficiency

New skills:
- cmk:learn — extract and record knowledge from any input to docs/knowledge/
- cmk:rule — codify engineering standards into docs/rules/ with promote workflow

Optimizations (30% fewer lines across all 8 skills):
- Add intent examples for better triggering accuracy
- Remove boilerplate (Content Guidance, redundant sections)
- Merge Quality Checklist + Output Contract into compact Output section
- Add NNNN numbering guidance to feature-spec and ADR
- Add status lifecycle to feature-spec (was missing)
- Make Security (system-design), Alternatives and Consequences (ADR) explicitly required
- Add docs/knowledge/ to scaffold manifest and orientation
- Add docs/knowledge/ as input source to prd, system-design, feature-spec

Author: daniellam258

.agents/skills/adr/SKILL.md

@@ -1,68 +1,61 @@
 ---
 name: cmk:adr
-description: Create or update architecture decision records for system-level technical choices. Use whenever users need to record, revise, or replace ADR decisions with clear trade-offs.
+description: Create or update architecture decision records for system-level technical choices. Use whenever someone needs to record, revise, or document a technical decision with trade-offs — like choosing a database, communication protocol, or infrastructure pattern. Also triggers for "record this decision", "we decided to use X over Y", or "document why we chose this approach".
 metadata:
   sdl_phase: "1"
   domain: "adr"
 ---
 
 # ADR
 
-Use this skill for:
-- Creating a new ADR from decision discussions
-- Updating an existing ADR when the decision evolves
+## Intents
 
-## Canonical References
+```
+We decided to use event sourcing over CRUD for the audit trail — record that as an ADR
+```
+```
+Record an ADR: chose Redis over Memcached for session caching because of pub/sub support
+```
+```
+Update ADR-0003 — we revisited the decision and switched from REST to gRPC
+```
+```
+Document why we chose Kafka over RabbitMQ
+```
+```
+What architecture decisions have we recorded?
+```
 
-- ADR conventions: `references/adr-conventions.md`
-- ADR template: `references/adr-template.md`
+## References
 
-## Content Guidance
+Read `references/adr-conventions.md` for placement rules and `references/adr-template.md` for section structure.
 
-Write what matters, skip what's obvious. The template is a starting point — adapt it to fit the context.
+## Scope
 
-## Decision Scope Rule
-
-Use ADRs only for system-level decisions that affect multiple features or core architecture.
-For feature-scoped decisions, keep them in the feature `spec.md` under Technical Decisions.
+ADRs are for system-level decisions that affect multiple features or core architecture. Feature-scoped decisions belong in the feature `spec.md` under Technical Decisions.
 
 ## Workflow: Create
 
-Use when no ADR exists for the decision.
-
 1. Gather decision context from conversation/docs/links.
-2. Validate that decision scope is system-wide.
-3. Apply canonical placement:
-   - Use the repository's existing canonical ADR path when available.
-   - Fallback path when no local convention exists: `docs/adrs/{NNNN}-{decision-title}.md`
-4. Fill template fields from `references/adr-template.md` (or local repository ADR template when present).
+2. Validate scope is system-wide (not feature-scoped).
+3. Place at the repository's existing ADR path, or fallback: `docs/adrs/{NNNN}-{decision-title}.md`. Determine `{NNNN}` by scanning existing ADRs and incrementing (start at `0001` if none exist).
+4. Fill template from `references/adr-template.md` (or local template if present).
 5. Set status to `proposed`.
 
 ## Workflow: Iterate
 
-Use when a decision has changed and the existing ADR needs to reflect the current state.
-
-1. Read the existing ADR in full before making changes.
+1. Read the existing ADR in full.
 2. **Upstream check:** If `docs/system-design.md` exists, check whether the revised decision conflicts with current architecture. Warn the user if so.
-3. Identify what changed and why — new constraints, better alternatives discovered, lessons from implementation.
-4. Update the ADR in place:
-   - **Revise Chose and Rationale** — reflect the current decision and why it shifted
-   - **Update Alternatives** — add newly considered options or remove irrelevant ones
-   - **Update Consequences** — revise based on actual impact observed
-   - **Note what changed** — add a brief note in rationale explaining what shifted from the prior decision
+3. Identify what changed and why.
+4. Update in place: revise decision/rationale, update alternatives and consequences, note what shifted.
 5. Update `Last updated` date.
-6. Transition status when appropriate:
-   - `proposed` → `accepted` when the team agrees
-   - `accepted` stays `accepted` when the decision evolves but remains active
+6. Transition status: `proposed` → `accepted` when team agrees. `accepted` stays `accepted` when decision evolves.
 
-## Quality Checklist
+## Output
 
+- Create: complete ADR file using canonical naming
+- Iterate: update in place with current decision and rationale
 - Decision statement is clear and implementable
-- Alternatives are explicit and meaningful
-- Trade-offs are concrete (cost, complexity, risk, performance)
+- Alternatives section is always present with concrete trade-offs
+- Consequences section is always present with short-term and long-term impact
 - If decision changed, rationale explains what shifted
-
-## Output Contract
-
-- If creating: produce a complete ADR file using canonical naming
-- If iterating: update the ADR in place with current decision and rationale

.agents/skills/codebase-summary/SKILL.md

@@ -1,75 +1,58 @@
 ---
 name: cmk:codebase-summary
-description: Create or iterate codebase summary documents. Use whenever users ask to document, update, or map the repository structure, key entry points, core modules, and local development setup.
+description: Create or iterate codebase summary documents that map repository structure, key entry points, core modules, and local dev setup. Use whenever someone wants to document how the repo is organized, update the codebase map after restructuring, or help new contributors navigate the codebase. Also triggers for "map the repo", "document the project structure", or "where does everything live".
 metadata:
   sdl_phase: "1"
   domain: "codebase-summary"
 ---
 
 # Codebase Summary
 
-Use this skill for:
-- Creating a new codebase summary for a repository
-- Updating the summary when the codebase structure changes
+## Intents
 
-## Canonical References
+```
+Document the repository structure and key entry points
+```
+```
+Update the codebase summary — we reorganized the src/ directory
+```
+```
+Map the codebase so new contributors can get oriented quickly
+```
+```
+Where does everything live in this project?
+```
 
-- Codebase summary conventions: `references/codebase-summary-conventions.md`
-- Codebase summary template: `references/codebase-summary-template.md`
+## References
 
-## Supported Input Sources
+Read `references/codebase-summary-conventions.md` for placement rules and `references/codebase-summary-template.md` for section structure.
 
-Collect and synthesize from one or more of:
-- Direct codebase exploration (directory structure, entry points, module boundaries)
-- Existing documentation (README, system-design, package.json, Cargo.toml, etc.)
-- Current conversation context
-- Direct prompt from the engineer
+## Scope
 
-## Content Guidance
+Codebase summary captures repository structure and navigation — how to find things. Architecture rationale belongs in system-design; feature behavior in specs.
 
-Write what matters, skip what's obvious. The template is a starting point — adapt it to fit the context.
+## Input
 
-## Scope Rule
-
-Codebase summary captures repository structure and navigation — how to find things and understand what lives where. Keep architecture rationale in system-design and feature behavior in specs.
+Synthesize from: direct codebase exploration (directories, entry points, modules), existing docs (README, package.json, etc.), conversation context, or direct prompts.
 
 ## Workflow: Create
 
-Use when no codebase summary exists.
-
-1. Explore the repository structure to understand layout, entry points, and module boundaries.
-2. Map findings into template sections in `references/codebase-summary-template.md`.
-   - If the target repository already has an existing convention, align to that local standard.
-3. Apply canonical placement:
-   - Use the repository's existing path when available.
-   - Fallback path when no local convention exists: `docs/codebase-summary.md`
-4. Include local development commands if discoverable from the codebase.
+1. Explore the repository to understand layout, entry points, and module boundaries.
+2. Map into template sections from `references/codebase-summary-template.md`. Align to local convention if one exists.
+3. Place at the repository's existing path, or fallback: `docs/codebase-summary.md`.
+4. Include local dev commands if discoverable.
 
 ## Workflow: Iterate
 
-Use when the codebase has changed and the summary needs to reflect the current state.
-
-1. Read the existing codebase summary in full before making changes.
-2. Explore the current codebase structure to identify what changed.
-3. Apply changes to the relevant sections:
-   - **Update Repository Layout** — reflect new/moved/removed directories
-   - **Update Key Entry Points** — add new entry points, remove stale ones
-   - **Update Core Modules** — add new modules, revise responsibilities, remove deprecated ones
-   - **Update Data and Integration Paths** — reflect new flows or changed integrations
-   - **Update Local Development Commands** — reflect changed setup, test, or build commands
-4. Preserve content that is still valid — do not rewrite sections that haven't changed.
-5. Update `Last updated` date.
-
-## Quality Checklist
-
-- Repository layout matches the actual directory structure
-- Entry points are accurate and current
-- Core modules table covers the important parts without listing every file
-- Local development commands are runnable
-- No architecture rationale (that belongs in system-design)
+1. Read the existing summary in full.
+2. Explore current codebase to identify what changed.
+3. Update affected sections in place. Preserve unchanged content.
+4. Update `Last updated` date.
 
-## Output Contract
+## Output
 
-- If creating: produce a complete codebase summary at `docs/codebase-summary.md`
-- If iterating: apply targeted updates to affected sections while preserving valid existing content
-- Always update `Last updated` date when iterating
+- Create: complete codebase summary at `docs/codebase-summary.md`
+- Iterate: targeted updates to affected sections only
+- Layout matches actual directory structure
+- Entry points and dev commands are current and runnable
+- No architecture rationale (belongs in system-design)

.agents/skills/docs/SKILL.md

@@ -1,95 +1,55 @@
 ---
 name: cmk:docs
-description: Bootstrap or update the /docs directory structure with AGENTS.md navigation files, README.md guides, and templates. Use when initializing a new repository, verifying an existing docs structure, or syncing docs scaffolding after devkit updates.
+description: Bootstrap or update the /docs directory structure with navigation files, guides, and templates. Use when someone wants to set up docs for a new repo, check if their docs structure is current, or sync scaffolding after devkit updates. Also triggers when users mention "docs structure", "initialize docs", or "docs scaffold".
 metadata:
   sdl_phase: "0"
   domain: "docs"
 ---
 
-# Docs Init
+# Docs
 
-Use this skill for:
-- Bootstrapping a new repository with the standard docs structure
-- Verifying and filling gaps in an existing docs structure
-- Updating navigation and template files after devkit changes
+## Intents
 
-## Canonical References
+```
+Set up the docs structure for this project
+```
+```
+Check if our docs structure matches the latest devkit
+```
+```
+We added a new service — update the docs scaffold
+```
+```
+Are we missing any docs directories?
+```
 
-- Directory structure and file manifest: `references/scaffold-manifest.md`
-- Template files: sourced from `docs/templates/` in the devkit
+## References
 
-## Modes
-
-### Init (default)
-
-First-time scaffolding. Creates missing directories, navigation files, and templates.
-
-- Never overwrites existing files
-- Reports divergences without modifying them
+Read `references/scaffold-manifest.md` for the complete file manifest and exact content for each file.
 
-### Update
-
-Re-sync an existing docs structure. Use when the devkit adds new templates, directories, or navigation patterns.
+## Modes
 
-- Creates any newly added directories and files that don't exist yet
-- For AGENTS.md and README.md files: compares against scaffold manifest and reports divergences
-- For templates: adds new templates that don't exist; never overwrites customized templates
-- Updates `docs/README.md` directory listing and template links when new entries are added
-- Always confirms with the user before modifying any existing file
+**Init** (default) — First-time scaffolding. Create missing directories, navigation files, and templates. Never overwrite existing files. Report divergences.
 
-### Verify
+**Update** — Re-sync after devkit changes. Create newly added files, compare AGENTS.md/README.md against manifest and report divergences, add new templates without overwriting customized ones. Confirm with user before modifying existing files.
 
-Dry-run check. Reports gaps and divergences without creating or modifying anything.
+**Verify** — Dry-run. Report gaps and divergences without creating or modifying anything.
 
 ## Workflow
 
-1. Determine mode from user intent (init, update, or verify).
-2. Scan the target repository for existing `/docs` structure.
-3. Compare against the scaffold manifest in `references/scaffold-manifest.md`.
-4. Execute based on mode:
-   - **Init:** create missing directories and files, skip existing
-   - **Update:** create missing, report divergences, offer to update existing with confirmation
-   - **Verify:** report only, no file changes
-5. Copy templates into `docs/templates/` when they do not already exist.
-6. Report what was created, skipped, diverged, and (in update mode) updated.
-
-## Directory Creation Order
-
-Create directories before their contents:
+1. Determine mode from user intent.
+2. Scan target repository for existing `/docs` structure.
+3. Compare against `references/scaffold-manifest.md`.
+4. Execute based on mode (init → create missing; update → create missing + offer fixes; verify → report only).
+5. Create directories before contents, in order: `docs/`, `templates/`, `adrs/`, `specs/`, `rules/`, `rules/common/`, `knowledge/`, `guides/`, `reference/`.
+6. For each directory, create `AGENTS.md` first, then `README.md`.
+7. Report: created, skipped, diverged, updated.
 
-1. `docs/`
-2. `docs/templates/`
-3. `docs/adrs/`
-4. `docs/specs/`
-5. `docs/rules/`
-6. `docs/rules/common/`
-7. `docs/guides/`
-8. `docs/reference/`
-
-## File Creation Order
-
-For each directory, create files in this order:
-
-1. `AGENTS.md` — agent navigation entry point
-2. `README.md` — human-readable structure and conventions
-
-Then create top-level docs:
-
-1. `docs/README.md` — directory structure and conventions overview
-2. Root `AGENTS.md` — project-level entry pointing to `/docs`
-
-## Quality Checklist
+## Output
 
 - Every directory has both `AGENTS.md` and `README.md`
-- Root `AGENTS.md` points to `docs/AGENTS.md`
-- `docs/AGENTS.md` points to `docs/README.md`
-- All subdirectory `AGENTS.md` files point to their local `README.md`
-- `docs/README.md` lists all directories and templates
+- Root `AGENTS.md` → `docs/AGENTS.md` → `docs/README.md` chain is intact
 - Templates directory contains all baseline templates
-
-## Output Contract
-
-- Report created files, skipped files (already existed), divergences, and updates applied
-- In init mode: never modify existing files
-- In update mode: confirm with user before modifying any existing file
-- In verify mode: no file changes, report only
+- Init mode never modifies existing files
+- Update mode confirms before modifying
+- Verify mode makes no file changes