framework-core

# Framework Core Skill Core skill that establishes workflow context for all katachi framework commands. ## When to Load All framework commands should load this skill first to establish: - Collaborative workflow principles - Status tracking conventions - Scratchpad usage patterns - Context bridging guidelines - Decision type guidance (ADR vs DES) ## Project Templates These templates are used when creating project structure: **Planning documents:** - `references/VISION-template.md` - Vision document structure - `references/DELTAS-template.md` - Delta inventory structure (work tracking) **Decision documents:** - `references/ADR-template.md` - Architecture Decision Record format - `references/DES-template.md` - Design Pattern document format **Feature documentation:** - `../working-on-delta/references/feature-spec.md` - Long-lived feature specification - `../working-on-delta/references/feature-design.md` - Long-lived feature design - `../working-on-delta/references/feature-domain-readme.md` - Domain index template - `../working-on-delta/references/feature-specs-readme.md` - Top-level feature index **Delta working documents:** - `../working-on-delta/references/delta-spec.md` - Delta specification (working doc) - `../working-on-delta/references/delta-design.md` - Delta design (working doc) - `../working-on-delta/references/implementation-plan.md` - Implementation plan (working doc) **Guidance documents** (how to write each document type): - `../working-on-delta/references/spec-template.md` - How to write delta specifications - `../working-on-delta/references/design-template.md` - How to write design rationale - `../working-on-delta/references/plan-template.md` - How to write implementation plans ## Decision Types Reference Load `references/decision-types.md` when: - Creating a new decision document (ADR or DES) - Determining which document type to use for a pattern/choice - Retrofitting existing decisions from code - Teaching users about ADR vs DES distinction This reference contains the full decision tree and examples for choosing between ADRs (one-time architectural choices) and DES (repeatable patterns). ## State Detection Before executing any command, detect project state: ### 1. Not Initialized **Condition:** No `docs/planning/` directory exists **Action:** - If no significant code exists → Offer `/katachi:init-framework` - If code exists → Explain retrofit options ### 2. Partially Initialized **Condition:** `docs/planning/` exists but missing VISION.md or DELTAS.md **Action:** - List what's missing - Offer to complete setup - Show which commands to run ### 3. Fully Initialized **Condition:** All planning files exist **Action:** - Proceed with normal command operation - Show current focus from CLAUDE.md if available ### 4. Retrofit Mode **Condition:** Code exists but no framework documentation **Action:** - Explain retrofit commands available - Offer `/katachi:retrofit-spec` for existing modules - Offer `/katachi:retrofit-decision` for existing patterns --- ## Workflow Principles Common principles for all collaborative command workflows in this framework. ### Core Principles #### 1. One Question at a Time Never batch multiple questions. Wait for answer before proceeding. **Why:** Prevents cognitive overload, maintains clear conversation flow, ensures each decision gets proper attention. #### 2. Propose, Don't Decide Agent proposes options, user confirms. Never add or change anything without user agreement. **Why:** User is the architect, Claude is the implementer. Maintain this relationship throughout. #### 3. Use AskUserQuestion for Structured Options When presenting 2-4 distinct choices, use the AskUserQuestion tool: - Provide clear header (max 12 chars, e.g., "Logging", "Format", "Approach") - Write complete question text - Add description explaining each option and its implications - Use `multiSelect: true` if choices aren't mutually exclusive - Examples: installation modes, logging approaches, technical choices, format options **When to use plain text instead:** - Open-ended questions (no predefined options) - Single simple clarification needed - Asking for creative input - Yes/no questions #### 4. Detect Gaps Proactively Throughout the entire process: - Surface unstated assumptions by asking about them - Identify potential edge cases and ask user if they're relevant - Challenge vague or incomplete answers - Ask "what could go wrong?" and "what's missing?" - Never fill gaps yourself - always ask the user #### 5. Use a Scratchpad Track state in `/tmp/<command>-state.md`: **Commands with natural IDs:** - For `-delta` commands, include the delta ID: `/tmp/<command>-<FEATURE-ID>-state.md` - `/spec-delta`: `/tmp/spec-<FEATURE-ID>-state.md` - `/design-delta`: `/tmp/design-<FEATURE-ID>-state.md` - `/plan-delta`: `/tmp/plan-<FEATURE-ID>-state.md` - `/implement-delta`: `/tmp/implement-<FEATURE-ID>-state.md` **Commands without natural IDs (parallel execution support):** - Generate unique animal-adjective ID: `/tmp/<command>-<animal-adjective>-state.md` - `/add-delta`: `/tmp/add-delta-<animal-adjective>-state.md` - `/analyze`: `/tmp/analyze-<animal-adjective>-state.md` - `/analyze-impact`: `/tmp/analyze-impact-<animal-adjective>-state.md` - `/decision`: `/tmp/decision-<animal-adjective>-state.md` - `/review-code`: `/tmp/review-code-<animal-adjective>-state.md` - Enables multiple concurrent sessions without state file conflicts - Keep state files after completion (don't auto-clean) for debugging/audit trail **Commands scoped by project name (directory basename):** - `/vision`, `/deltas`, `/dependencies` - Use `/tmp/<command>-<project-name>-state.md` **Commands without scratchpads:** - `/commit`, `/record-learnings` - No scratchpad needed **Scratchpad contents:** - Current section/phase being worked on - Questions asked and answered - Gaps identified - Topics to revisit - Decisions made **Why:** Prevents information loss across question rounds, maintains context during iteration. #### 6. Bridge the Context Gap The agent reads multiple files (specs, designs, ADRs, DES patterns) and builds comprehensive context. The user reads documents when needed but doesn't have the full picture simultaneously. **When asking questions or explaining decisions:** - Include diagrams (ASCII art, sequence diagrams, thread/data flows) - Provide rich context - don't assume shared understanding - Explain the "why" behind technical questions - Show concrete examples, not abstract references - Name the specific files, components, or patterns being referenced #### 7. Research When Needed When user shows uncertainty, research to provide informed options. **Research triggers:** - User says "I'm not sure" or "I don't know" - Topic involves technical choices (models, libraries, protocols, frameworks) - User asks "what options do I have?" - User mentions alternatives they've tried but weren't satisfied with Use Task tool (general-purpose agent) to research, then synthesize findings to inform questions. #### 8. Document the Present, Not the Past All documentation describes the **current** system — what it does and what it deliberately does not do. Never phrase anything as what the system *used to* do or what was replaced. Frame decisions positively: state what is implemented and why, then record alternatives as options *considered and not chosen*, with reasons. - ❌ "The system doesn't implement `X` because it was replaced by `Y`." - ✅ "The system implements `Y` (because `W` and `Z`). `A` and `B` were considered and not chosen (because `C`)." The only sanctioned place for history is an ADR's `Status: Superseded by ADR-XXX` line — and even there, the body describes the current decision. **Why:** Documentation is read as the source of truth for the current system. References to prior implementations confuse readers who never saw them, age badly, and turn living documents into changelogs. #### 9. Match Altitude to the Artifact Each document describes the system at its own level of abstraction; detail that belongs to a lower level is pushed down, not copied up. - **Spec** — behavior and constraints: *what* is guaranteed, as a user or consumer observes it. No libraries, APIs, or code shapes. - **Design** — approach and mechanism: parts by role, data flow, seams. Name a chosen technology only as a *decision* (pointing to its ADR), never its import paths, API/method surface, config literals, flags, or command syntax. A short **generic** snippet illustrating a *pattern* is welcome — but it stays illustrative (schematic shapes, pseudocode) and never reproduces the project's real imports, symbol names, or call signatures. - **ADR / DES** — the decision and *why*: name the concrete thing chosen (a library, a topology, a pattern), not how you call it. - **Code and operational docs** (README/runbook) — the only home for imports, exact commands, flags, and file paths. - ❌ (in a design) "Render the menu with `<Menu.Root>` from `@acme/ui/menu`, passing `collisionAvoidance={{ side: 'shift' }}`." - ✅ (in a design) "A headless menu, positioned in JS from the click point and shifted to stay on-screen; the concrete library is fixed in its ADR." Rule of thumb: if a detail would change in a refactor that alters neither the behavior nor the decision (an import path, a method name, a CLI flag), it does not belong in a durable spec/design/ADR. **Why:** A durable doc pinned to an import path or a command string rots the moment the code is refactored, and it buries the decision or behavior a reader needs under detail they could read from the code. Keeping each artifact at its altitude lets it survive change and stay readable to whoever only needs that level. ### Workflow Modes #### Information Gathering **Use for:** Understanding requirements, clarifying scope, exploring options **Workflow:** - Ask one question at a time - Wait for answer before proceeding - Use AskUserQuestion for structured choices - Build understanding incrementally #### Document Creation **Use for:** Specs, designs, plans, decisions **Workflow:** 1. **Research phase (silent, thorough)** - Read spec/requirements - Read relevant ADRs and DES patterns - Explore related codebase areas if needed - Research official documentation for libraries/frameworks/APIs - Build understanding without asking upfront questions 2. **Draft proposal (with decision points)** - Create complete document following template - Base all choices on research findings - Note any uncertainties/assumptions clearly - **If choices require user input:** Use AskUserQuestion (ambiguous requirements, multiple valid approaches, trade-offs) 3. **External validation (silent)** - Dispatch appropriate reviewer agent - Agent provides structured feedback 4. **Apply validation feedback (silent, with decision points)** - Apply ALL recommendations automatically - **If applying requires a choice:** Use AskUserQuestion (multiple valid fixes, conflicts with earlier decisions) - Track changes for presentation 5. **Present validated document** - Show complete document to user - Include summary of applied validation fixes - Highlight unresolved issues - Invite user feedback: "What needs adjustment?" 6. **Iterate based on user feedback** - Apply user corrections/additions - Re-run validation if significant changes - Repeat until user approves 7. **Finalize** - Write document to file - Update status **Key principle:** Validate before presenting, auto-apply fixes. Only use AskUserQuestion for genuine decisions (multiple valid options), not for fixes. ### Validation Best Practices #### Use Custom Agents for Validation Dispatch the appropriate reviewer agent for validation: | Document Type | Reviewer Agent | |--------------|----------------| | Delta Spec | `katachi:spec-reviewer` | | Delta Design | `katachi:design-reviewer` | | Implementation Plan | `katachi:plan-reviewer` | | Implemented Code | `katachi:code-reviewer` | | Change Impact | `katachi:impact-analyzer` | | Existing Code | `katachi:codebase-analyzer` | Dispatch agents using the Task tool with appropriate `subagent_type`. #### Validation Context Balance fresh perspective with respecting user decisions: **Include in validation context:** - The artifact being validated (spec, design, code, etc.) - Relevant templates and examples - User's explicit decisions and constraints - Project-wide patterns (ADRs, DES documents) **Exclude from validation context:** - Agent's internal reasoning and discussion history - Intermediate drafts and iterations - Unrelated project context ### Collaborative Process **This is always a collaborative process:** - Ask one question at a time - Agent proposes, user confirms - never decide without agreement - User makes all decisions - Provide alternatives and trade-offs (research-backed when needed) - Never fill gaps yourself - always ask the user - Use AskUserQuestion for structured options (2-4 choices) - Iterate until the user approves the final result --- ## Shape Up Integration Katachi adopts specific elements from Ryan Singer's Shape Up methodology to make the spec and design phases more collaborative. Katachi keeps its own phase structure (spec → design → plan → implement). ### What We Use #### Requirements Table (R) Compact, prioritized problem-space summary included in delta specs. Built collaboratively with the user during the spec interview — not generated by the agent alone. Each requirement has a status: `Core goal`, `Must-have`, `Nice-to-have`, or `Out`. Up to 30 top-level requirements; use sub-IDs (R3.1, R3.2) for grouping. Requirements state WHAT is needed. Acceptance Criteria (Given/When/Then) define HOW to verify each requirement. #### Shape Parts Table Solution mechanisms included in delta designs. Built collaboratively with the user — the agent proposes mechanisms and the user refines before the shape is seeded. Each part describes what to build or change — a concrete mechanism, not a constraint (constraints belong in the spec's Requirements table). Parts have a flag column: empty = mechanism is understood, ⚠️ = unknown that needs investigation. Flagged parts must include a description below the table explaining what the unknown is. Flagged parts are resolved during design phase via research or spikes. The shape is seeded during spec phase (high-level mechanisms, collaboratively refined with user) and evolved during design phase (detailed mechanisms with unknowns resolved). #### Requirements Coverage Check Internal validation step used during spec and design phases. Not persisted in any document. After drafting shape parts, verify: - Every requirement (R) has at least one shape part addressing it — otherwise there's a missing mechanism - Every shape part traces back to at least one requirement — otherwise there's scope creep If the check reveals gaps, surface them to the user before proceeding. #### Spikes Lightweight investigation artifacts for resolving unknowns in shape parts. A spike asks specific questions, researches answers, and may surface new requirements that feed back to the spec. Spikes are dispatched as subagent tasks and validated with the user. Template: `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/spike-template.md` Location in projects: `docs/spikes/SPIKE-DLT-XXX-topic.md` ### Cross-Phase Flow 1. **Spec phase**: Builds R table collaboratively → derives AC from requirements → drafts initial shape → validates coverage internally → **refines shape collaboratively with user** → seeds design doc with user-approved shape 2. **Design phase**: Reads initial shape → resolves unknowns via spikes → evolves shape into full design → **presents evolved shape to user** → validates coverage against R --- ## Status Tracking Conventions for tracking delta progress through the development workflow. ### Status Symbols | Symbol | Meaning | |--------|---------| | ✗ | Not Started | | ⧗ | In Progress | | ✓ | Complete | ### Status Progression Deltas progress through these stages: ``` ✗ Defined (initial state - delta in DELTAS.md) ↓ ⧗ Spec (/spec-delta starts) ↓ ✓ Spec (/spec-delta completes) ↓ ⧗ Design (/design-delta starts) ↓ ✓ Design (/design-delta completes) ↓ ⧗ Plan (/plan-delta starts) ↓ ✓ Plan (/plan-delta completes) ↓ ⧗ Implementation (/implement-delta starts) ↓ ✓ Implementation (/implement-delta completes) ``` ### When to Update Status #### At Command Start Set status to in-progress state (⧗) for the current phase. Example: `/spec-delta CORE-001` → set status to "⧗ Spec" #### At Command Completion Set status to complete state (✓) for the current phase. Example: `/spec-delta CORE-001` finishes → set status to "✓ Spec" ### How to Update Status Use the deltas.py script: ```bash # Set status python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set FEATURE-ID "STATUS"