Design & Planning Tools (Stream D)

Stream D tools turn approved specs into actionable implementation artifacts — schemas, UI contracts, architecture decisions, execution plans, event contracts, and more.

Quick Reference

Tool	Description	Availability
`generate_adr`	Generate an Architecture Decision Record for a significant technical decision	Included
`log_decision`	Register, list, search, or supersede architectural and process decisions	Included
`design_schema`	Design and validate data schemas for your application	Included
`define_ui_contract`	Define and manage UI component contracts for design-to-code workflows	Included
`event_contracts`	Define and manage event-driven architecture contracts	Included
`generate_execution_plan`	Create a step-by-step execution plan for implementing a spec	Included
`generate_orchestration_script`	Generate a script for orchestrating multi-agent execution	Included
`recommend_model`	Recommend the best AI model tier for a given task	Included
`plan_team_distribution`	Plan how to distribute approved specs across a team of Claude Code agents	Included
`generate_spec_from_design`	Generate a Planu spec from a UI/UX design description	Included
`contribute_context`	Contribute additional context to a spec from external sources	Included
`request_context`	Request additional context or expertise from the knowledge base	Included
`generate_proposal`	Generate a self-contained HTML project proposal with KPI grid and Gantt chart	Included
`generate_docs_site`	Generate a static HTML documentation site from project specs	Included
`data_governance`	Set up data governance policies and data classification rules	Included
`legal_compliance_report`	Generate a compliance report for legal and regulatory requirements	Included
`federate_specs`	Link a spec in the current project to a spec in another local repository	Included
`federation_status`	Show all cross-repo spec federation links and their health	Included
`discover_registry`	Read and validate a `.well-known/planu.json` manifest from a local file path	Included
`publish_registry`	Generate a `.well-known/planu.json` manifest from your project specs	Included
`registry_publish`	Publish a spec to the Planu registry	Included
`registry_login`	Authenticate with the Planu spec registry using an API token	Included
`registry_logout`	Remove stored registry credentials	Included
`registry_whoami`	Show the currently authenticated registry user	Included
`a2a_register`	Register Planu as an A2A (Agent-to-Agent) capable agent	Included
`a2a_delegate`	Delegate a spec-related task to another A2A agent endpoint	Included

Architecture Decisions

`generate_adr`

Generate an Architecture Decision Record (ADR) for a significant technical decision.

What it produces: Structured ADR documents covering the decision context, options considered, decision made, and consequences. Format follows MADR (Markdown Architectural Decision Records).

When to use: When a spec involves a significant technology choice, architecture pattern, or trade-off that future developers need to understand.

Prompt: "Generate ADRs for spec SPEC-004 in project proj_abc123"

Example output:

markdown

# ADR-001: Use Redis for session storage

## Status: Accepted

## Context
The authentication spec requires session persistence across multiple server instances...

## Decision
Use Redis as the session store...

## Consequences
- Positive: Horizontal scaling without sticky sessions
- Negative: Adds Redis as a required infrastructure dependency

`log_decision`

Actions available: log, list, search, supersede

When to use: To maintain a searchable record of decisions made during the project — who decided what, why, and when. Supersede a previous decision when the team changes direction.

Prompt: "Log a decision: we will use PostgreSQL instead of MongoDB for project proj_abc123"
Prompt: "List all decisions for project proj_abc123"
Prompt: "Supersede decision DEC-003 with the new approach in project proj_abc123"

`design_schema`

Design and validate data schemas for your application.

What it produces:

Table definitions with columns, types, and constraints
Primary and foreign key relationships
Index suggestions for query performance
Migration hints
Schema in multiple dialects (SQL, Prisma, SQLAlchemy, GORM, etc.)

When to use: When a spec involves data persistence and you need a concrete starting point for the database layer.

Prompt: "Design the database schema for spec SPEC-002 in project proj_abc123"

`define_ui_contract`

Define and manage UI component contracts for design-to-code workflows.

What it produces:

Component interface definitions (props, events, slots)
Data flow diagram (which components own which state)
State management approach (local, context, store)
API contract between frontend and backend
Accessibility requirements

When to use: For any spec that includes a frontend component, form, or user interaction.

Prompt: "Define the UI contract for the login flow in spec SPEC-001 for project proj_abc123"

`event_contracts`

Define and manage event-driven architecture contracts — generate JSON Schema event contracts for producer/consumer validation.

What it produces:

JSON Schema definitions for each event type
Producer contract (what the emitter guarantees)
Consumer contract (what the subscriber expects)
Versioning strategy
Backward compatibility notes

When to use: For any spec that involves message queues, event buses (Kafka, RabbitMQ, AWS SQS/SNS, NATS), or webhook integrations.

Prompt: "Define event contracts for the order processing flow in spec SPEC-008 for project proj_abc123"

Example output:

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OrderPlaced",
  "version": "1.0.0",
  "type": "object",
  "required": ["orderId", "customerId", "items", "total", "placedAt"],
  "properties": {
    "orderId": { "type": "string", "format": "uuid" },
    "customerId": { "type": "string", "format": "uuid" },
    "items": { "type": "array", "items": { "$ref": "#/definitions/OrderItem" } },
    "total": { "type": "number", "minimum": 0 },
    "placedAt": { "type": "string", "format": "date-time" }
  }
}

Execution Planning

`generate_execution_plan`

Create a detailed, step-by-step execution plan for implementing a spec — RED/GREEN/VERIFY cycle with parallelizable steps.

What it produces:

markdown

## Phase 1: Foundation (parallel)
- [ ] Step 1a: Create database migration
- [ ] Step 1b: Define TypeScript interfaces
- [ ] Step 1c: Write failing tests (RED)

## Phase 2: Implementation (sequential)
- [ ] Step 2a: Implement repository layer (GREEN)
- [ ] Step 2b: Implement service layer

## Phase 3: Verification
- [ ] Step 3a: Run full test suite (VERIFY)
- [ ] Step 3b: Update spec status to review

When to use: Before implementation begins. The PLAN.md becomes the implementation contract for the AI agent or developer.

Prompt: "Generate an execution plan for spec SPEC-005 in project proj_abc123"

`generate_orchestration_script`

Generate a script for orchestrating multi-agent execution — creates a 3-layer parallel automation script using worktrees and claude -p.

What it produces: A shell script that:

Creates isolated git worktrees per spec
Launches claude -p workers in parallel
Manages resource allocation based on available CPU and RAM
Monitors worker health and handles failures

When to use: When you need to implement multiple independent specs simultaneously and want maximum parallelism.

Prompt: "Generate an orchestration script for specs SPEC-010, SPEC-011, SPEC-012 in project proj_abc123"

`recommend_model`

Recommend the best AI model tier (haiku, sonnet, or opus) for a given task based on complexity, cost, and capability requirements.

What it evaluates:

Task complexity (simple code gen vs. architecture decisions)
Cost constraints
Speed requirements
Reasoning depth needed

When to use: When choosing between AI models for implementation, code review, or spec generation.

Prompt: "Recommend a model for implementing spec SPEC-005 in project proj_abc123"

`plan_team_distribution`

Plan how to distribute approved specs across a team of Claude Code agents — assigns specs to agents based on dependencies, file ownership, and parallelism constraints.

What it produces:

Agent assignment table (which agent handles which specs)
Dependency graph to determine sequencing
File ownership map to prevent conflicts
Ready-to-use agent spawn prompts

When to use: When implementing multiple specs in parallel with an agent team. Prevents file conflicts and wasted work.

TIP

Run plan_team_distribution before launching any agent team. It catches file ownership conflicts that would otherwise cause merge nightmares.

Prompt: "Plan team distribution for approved specs in project proj_abc123"

Design from Input

`generate_spec_from_design`

Generate a Planu spec from a UI/UX design description — converts wireframes, mockup descriptions, or design notes into structured acceptance criteria.

When to use: When a designer hands off a description or image of a UI and you need to turn it into a buildable spec before implementation.

Prompt: "Generate a spec from this design: a dashboard with a sidebar nav, main content area, and a collapsing filters panel, for project proj_abc123"

`contribute_context`

Contribute additional context to a spec from external sources or domain expertise — appends structured knowledge to an existing spec.

When to use: When a subject matter expert (legal, security, compliance) needs to add constraints to a spec that the original author didn't have.

Prompt: "Contribute context to spec SPEC-003: GDPR requires data deletion within 30 days for project proj_abc123"

`request_context`

Request additional context or expertise from the knowledge base — queries learned patterns, past decisions, and domain knowledge relevant to a spec.

When to use: Before writing a spec in an unfamiliar domain to pull in relevant constraints and patterns from past projects.

Prompt: "Request context for a payments integration spec in project proj_abc123"

Export & Documentation

`generate_proposal`

Generate a self-contained HTML project proposal with KPI grid, Gantt chart, spec breakdown table, risk analysis, budget summary, and architecture overview.

What it produces: A single portable HTML file ready to share with clients or stakeholders — no server required.

When to use: When presenting a project plan to non-technical stakeholders or potential clients.

Prompt: "Generate a project proposal for project proj_abc123"

`generate_docs_site`

Generate a static HTML documentation site from project specs, tools catalog, architecture diagrams, and metrics.

What it produces:

A browsable HTML site covering all specs, their status, and acceptance criteria
Architecture diagrams derived from the spec graph
Searchable tools catalog
Exportable for hosting on any static server

When to use: When a project needs living documentation that stays in sync with specs.

Prompt: "Generate a documentation site for project proj_abc123"

Governance & Compliance

`data_governance`

Set up data governance policies and data classification rules for the project.

What it produces:

Data classification taxonomy (public, internal, confidential, restricted)
Governance policies per data class
Spec-level tagging for data handling requirements
Violation detection in future specs and code

When to use: For projects handling sensitive data — healthcare, finance, legal, or any regulated industry.

Prompt: "Set up data governance for project proj_abc123 under HIPAA"

`legal_compliance_report`

Generate a compliance report for legal and regulatory requirements — maps specs and implementation to specific regulation clauses.

What it produces:

Coverage report per regulation (GDPR, HIPAA, SOC 2, PCI DSS, etc.)
Open gaps that need remediation
Evidence links to specs and audit trail events
Exportable for legal review

When to use: Before a compliance audit or when preparing evidence packages for certification.

Prompt: "Generate a GDPR compliance report for project proj_abc123"

Federation & Registry

Federation lets you link specs across repositories. The registry allows publishing and discovering specs for reuse across teams and organizations.

`federate_specs`

Link a spec in the current project to a spec in another local repository — creates a cross-repo dependency link.

When to use: In monorepo or multi-repo setups where one project's spec depends on another project's spec.

Prompt: "Federate spec SPEC-005 in project proj_abc123 to spec SPEC-012 in project proj_xyz789"

`federation_status`

Show all cross-repo spec federation links and their health — checks that linked specs still exist and are in sync.

Prompt: "Show federation status for project proj_abc123"

`discover_registry`

Read and validate a .well-known/planu.json manifest from a local file path — shows what specs a project exposes for reuse.

Prompt: "Discover registry manifest at /workspace/shared-lib"

`publish_registry`

Generate a .well-known/planu.json manifest from your project specs — makes your specs discoverable by other projects.

Prompt: "Publish registry manifest for project proj_abc123"

`registry_publish`

Publish a spec to the Planu registry so other teams can discover and reuse it.

Prompt: "Publish spec SPEC-007 to the Planu registry from project proj_abc123"

`registry_login`

Authenticate with the Planu spec registry using an API token.

Prompt: "Log in to the Planu registry with my API token"

`registry_logout`

Remove stored registry credentials from the local machine.

Prompt: "Log out of the Planu registry"

`registry_whoami`

Show the currently authenticated registry user.

Prompt: "Who am I logged in as in the Planu registry?"

Agent-to-Agent (A2A)

A2A enables Planu to participate in multi-agent ecosystems — registering as a capable agent and delegating tasks to other specialized agents.

`a2a_register`

Register Planu as an A2A (Agent-to-Agent) capable agent — publishes Planu's capabilities to an A2A endpoint so other agents can discover and delegate to it.

When to use: When integrating Planu into a multi-agent pipeline where other orchestrators need to know what Planu can do.

Prompt: "Register Planu as an A2A agent for project proj_abc123"

`a2a_delegate`

Delegate a spec-related task to another A2A agent endpoint — sends a structured task request to an external agent and receives the result.

When to use: When another specialized agent (e.g., a code review agent, a deployment agent) should handle a step in the Planu workflow.

Prompt: "Delegate the code review for spec SPEC-009 to the review agent at http://localhost:8080 in project proj_abc123"

Design & Planning Tools (Stream D) ​

Quick Reference ​

Architecture Decisions ​

generate_adr ​

log_decision ​

design_schema ​

define_ui_contract ​

event_contracts ​

Execution Planning ​

generate_execution_plan ​

generate_orchestration_script ​

recommend_model ​

plan_team_distribution ​

Design from Input ​

generate_spec_from_design ​

contribute_context ​

request_context ​

Export & Documentation ​

generate_proposal ​

generate_docs_site ​

Governance & Compliance ​

data_governance ​

legal_compliance_report ​

Federation & Registry ​

federate_specs ​

federation_status ​

discover_registry ​

publish_registry ​

registry_publish ​

registry_login ​

registry_logout ​

registry_whoami ​

Agent-to-Agent (A2A) ​

a2a_register ​

a2a_delegate ​

See Also ​

Design & Planning Tools (Stream D)

Quick Reference

Architecture Decisions

`generate_adr`

`log_decision`

`design_schema`

`define_ui_contract`

`event_contracts`

Execution Planning

`generate_execution_plan`

`generate_orchestration_script`

`recommend_model`

`plan_team_distribution`

Design from Input

`generate_spec_from_design`

`contribute_context`

`request_context`

Export & Documentation

`generate_proposal`

`generate_docs_site`

Governance & Compliance

`data_governance`

`legal_compliance_report`

Federation & Registry

`federate_specs`

`federation_status`

`discover_registry`

`publish_registry`

`registry_publish`

`registry_login`

`registry_logout`

`registry_whoami`

Agent-to-Agent (A2A)

`a2a_register`

`a2a_delegate`

See Also