Load when working with any katachi framework command. Provides workflow principles, status tracking conventions, and decision guidance. This skill establishes the collaborative context for all framework operations.
Establishes collaborative workflow context for all katachi framework commands. Loads when any framework command runs to provide status tracking, decision guidance (ADR vs DES), and scratchpad patterns for coordinated development.
/plugin marketplace add asermax/claude-plugins/plugin install katachi@asermax-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/ADR-template.mdreferences/BACKLOG-template.mdreferences/DEPENDENCIES-template.mdreferences/DES-template.mdreferences/FEATURES-template.mdreferences/VISION-template.mdreferences/decision-types.mdCore skill that establishes workflow context for all katachi framework commands.
All framework commands should load this skill first to establish:
These templates are used when creating project structure:
references/VISION-template.md - Vision document structurereferences/FEATURES-template.md - Feature inventory structurereferences/DEPENDENCIES-template.md - Dependency matrix structurereferences/BACKLOG-template.md - Backlog for bugs, ideas, improvements, tech-debt, questionsreferences/ADR-template.md - Architecture Decision Record formatreferences/DES-template.md - Design Pattern document formatLoad references/decision-types.md when:
This reference contains the full decision tree and examples for choosing between ADRs (one-time architectural choices) and DES (repeatable patterns).
The backlog tracks items not ready for full feature treatment:
/review-code/add-feature/review-code/review-code/decisionUse ${CLAUDE_PLUGIN_ROOT}/scripts/backlog.py for management:
python ${CLAUDE_PLUGIN_ROOT}/scripts/backlog.py list # List open items
python ${CLAUDE_PLUGIN_ROOT}/scripts/backlog.py show ID # Show item details
python ${CLAUDE_PLUGIN_ROOT}/scripts/backlog.py add TYPE "TITLE" --priority N
python ${CLAUDE_PLUGIN_ROOT}/scripts/backlog.py fix ID # Mark as fixed
python ${CLAUDE_PLUGIN_ROOT}/scripts/backlog.py promote ID --feature FEATURE-ID
Priority scale: 1=critical, 2=high, 3=medium, 4=low, 5=someday
Before executing any command, detect project state:
Condition: No planning/ directory exists
Action:
/katachi:init-frameworkCondition: planning/ exists but missing VISION.md, FEATURES.md, or DEPENDENCIES.md
Action:
Condition: All planning files exist
Action:
Condition: Code exists but no framework documentation
Action:
/katachi:retrofit-spec for existing modules/katachi:retrofit-decision for existing patternsCommon principles for all collaborative command workflows in this framework.
Never batch multiple questions. Wait for answer before proceeding.
Why: Prevents cognitive overload, maintains clear conversation flow, ensures each decision gets proper attention.
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.
When presenting 2-4 distinct choices, use the AskUserQuestion tool:
multiSelect: true if choices aren't mutually exclusiveWhen to use plain text instead:
Throughout the entire process:
Track state in /tmp/<command>-state.md:
Commands with natural IDs:
-feature commands, include the feature ID: /tmp/<command>-<FEATURE-ID>-state.md
/spec-feature: /tmp/spec-<FEATURE-ID>-state.md/design-feature: /tmp/design-<FEATURE-ID>-state.md/plan-feature: /tmp/plan-<FEATURE-ID>-state.md/implement-feature: /tmp/implement-<FEATURE-ID>-state.mdCommands without natural IDs (parallel execution support):
/tmp/<command>-<animal-adjective>-state.md
/add-feature: /tmp/add-feature-<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.mdCommands that don't need parallel support:
/vision, /features, /dependencies - Sequential execution sufficient, use /tmp/<command>-state.mdCommands without scratchpads:
/commit, /record-learnings - No scratchpad neededScratchpad contents:
Why: Prevents information loss across question rounds, maintains context during iteration.
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:
When user shows uncertainty, research to provide informed options.
Research triggers:
Use Task tool (general-purpose agent) to research, then synthesize findings to inform questions.
Use for: Understanding requirements, clarifying scope, exploring options
Workflow:
Use for: Specs, designs, plans, decisions
Workflow:
Research phase (silent, thorough)
Draft proposal
Present for review
Iterate
Finalize
Key principle: Always draft first, no upfront questions. Questions happen during review phase.
Dispatch the appropriate reviewer agent for validation:
| Document Type | Reviewer Agent |
|---|---|
| Feature Spec | katachi:spec-reviewer |
| Feature 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.
Balance fresh perspective with respecting user decisions:
Include in validation context:
Exclude from validation context:
This is always a collaborative process:
Conventions for tracking feature progress through the development workflow.
| Symbol | Meaning |
|---|---|
| ✗ | Not Started |
| ⧗ | In Progress |
| ✓ | Complete |
Features progress through these phases:
✗ Defined (initial state - feature in FEATURES.md)
↓
⧗ Spec (/spec-feature starts)
↓
✓ Spec (/spec-feature completes)
↓
⧗ Design (/design-feature starts)
↓
✓ Design (/design-feature completes)
↓
⧗ Plan (/plan-feature starts)
↓
✓ Plan (/plan-feature completes)
↓
⧗ Implementation (/implement-feature starts)
↓
✓ Implementation (/implement-feature completes)
Set status to in-progress state (⧗) for the current phase.
Example: /spec-feature CORE-001 → set status to "⧗ Spec"
Set status to complete state (✓) for the current phase.
Example: /spec-feature CORE-001 finishes → set status to "✓ Spec"
Use the features.py script:
# Set status
python scripts/features.py status set FEATURE-ID "STATUS"
# Examples
python scripts/features.py status set CORE-001 "⧗ Spec"
python scripts/features.py status set CORE-001 "✓ Spec"
python scripts/features.py status set CORE-001 "⧗ Design"
# List all features with status
python scripts/features.py status list
# Filter by phase
python scripts/features.py status list --phase 1
# Filter by category
python scripts/features.py status list --category CORE
# Filter by status
python scripts/features.py status list --status "✓ Spec"
# Show detailed feature status
python scripts/features.py status show CORE-001
Status is stored in FEATURES.md as a column:
| ID | Description | Complexity | Status |
|----|-------------|------------|--------|
| CORE-001 | Feature description | Medium | ✓ Design |
| CORE-002 | Another feature | Easy | ⧗ Spec |
A feature is ready to implement when:
Use this command to check:
python scripts/features.py ready
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.