plan
Execute the implementation planning workflow using the plan template to generate design artifacts.
SKILL.mdskills/plan/SKILL.md
GitHubUser Input
You MUST consider the user input before proceeding (if not empty).
Outline
Setup: Call the
akka_sdd_list_specsMCP tool to find the target feature. Then callakka_sdd_get_templatewith template_name="plan" to get the plan template. Identify the feature's spec path (FEATURE_SPEC) and plan destination (FEATURE_DIR/plan.md).Load context: Read FEATURE_SPEC and
akka_sdd_constitution. If the spec contains unresolved [NEEDS CLARIFICATION] markers for policy decisions (thresholds, access permissions, retention, sensitive-data rules, approvals), report them, recommend/akka:clarify, and stop; do not decide them through research. Load IMPL_PLAN template (already copied).Execute plan workflow: Follow the structure in IMPL_PLAN template to:
- Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
- If the spec involves agents or model-generated behavior: check the project's installed Akka SDK version and its local documentation before choosing guardrail, classifier, sanitizer, evaluator, or identity mechanisms. Do not assume features newer than that version and do not upgrade the Akka SDK implicitly; if a required feature needs a newer version, record the upgrade as an explicit decision in research.md.
- Fill Constitution Check section from constitution
- Evaluate gates (ERROR if violations unjustified)
- Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
- Phase 1: Map domain concepts to Akka components (Component Architecture table), then generate data-model.md, contracts/, quickstart.md
- Re-evaluate Constitution Check post-design
Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
Phases
Phase 0: Outline & Research
Extract unknowns from Technical Context above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
Generate and dispatch research agents:
For each unknown in Technical Context: Task: "Research {unknown} for {feature context}" For each technology choice: Task: "Find best practices for {tech} in {domain}"Consolidate findings in
research.mdusing format:- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
Output: research.md with all NEEDS CLARIFICATION resolved
Phase 1: Design & Contracts
Prerequisites: research.md complete
Map domain concepts to Akka components → the Component Architecture table in plan.md:
- Read the "Choosing a component type" section in
akka-context/sdk/components/index.html.md(first time in session) before mapping - For each domain concept, process, and query in the spec, choose the component per the decision guide: entity type (Key Value vs Event Sourced), Workflow vs Consumer, whether a View is needed, endpoint type, or a plain domain class instead of a component
- Record every choice in the table with the reason. Where the decision guide names a close alternative (entity type, view vs direct entity read, workflow vs consumer, timed action vs workflow timer), also record the rejected alternative and why it was not chosen
- ERROR if a close-call row lacks the rejected alternative
- Read the "Choosing a component type" section in
Extract entities from feature spec →
data-model.md:- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
Define interface contracts (if project has external interfaces) →
/contracts/:- Identify what interfaces the project exposes to users or other systems
- Document the contract format appropriate for the project type
- Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
- Skip if project is purely internal (build scripts, one-off tools, etc.)
Agent context update:
- Agent context files are managed automatically by the Akka CLI when running
akka_sdd_init. No manual agent context update is needed.
- Agent context files are managed automatically by the Akka CLI when running
Output: Component Architecture table in plan.md, data-model.md, /contracts/*, quickstart.md
Key rules
- Use absolute paths
- ERROR on gate failures or unresolved clarifications
Done When
- FEATURE_DIR, FEATURE_SPEC, and the plan template were resolved via
akka_sdd_list_specsandakka_sdd_get_template. - Technical Context is filled with concrete values; any remaining unknowns are explicitly marked
NEEDS CLARIFICATION. - Constitution Check was filled from
akka_sdd_constitution, evaluated before Phase 0, and re-evaluated after Phase 1 design — with any violations either resolved or explicitly justified in the Complexity Tracking section. - Phase 0 produced
research.mdwith everyNEEDS CLARIFICATIONresolved (Decision / Rationale / Alternatives). - The Component Architecture table in
plan.mdmaps every domain concept, process, and query to a component (or a plain domain class), with close-call rows naming the rejected alternative and why it was not chosen — informed by the "Choosing a component type" section ofakka-context/sdk/components/index.html.md. - Phase 1 produced
data-model.md,quickstart.md, and — if the project exposes external interfaces —contracts/. -
FEATURE_DIR/plan.mdwas written using the template structure and no gate error was left unresolved. - Completion was reported with the branch, plan path, generated artifacts, and the next-command recommendation (
/akka:tasks).