1## Context23The plugin already has two classes of agent tools: CLI-backed wrappers (`openspec_list`, `openspec_show`, `openspec_validate`, `openspec_status`, `openspec_instructions`) and filesystem-backed context resolution (`openspec_context`). Ideas are already part of the dashboard scan model under `openspec/ideas/`, but agents had no write-side primitive for capturing, enriching, or promoting ideas.45The new idea tools are filesystem-backed because OpenSpec CLI currently has no `openspec new idea` command. They still follow existing plugin conventions: JSON string responses, `ok: true/false`, explicit validation errors, `workdir` support, and registered-source identifier support where possible.67## Goals / Non-Goals89**Goals:**1011- Create idea markdown files deterministically under `openspec/ideas/`.12- Let agents update a structured enrichment section without duplicating old reports.13- Promote reviewed ideas into valid OpenSpec change scaffolds that preserve traceability.14- Keep the tools usable even when the OpenSpec CLI binary is unavailable.15- Keep generated artifacts simple enough for humans to review and refine.1617**Non-Goals:**1819- Automatically spawning subagents from `openspec_idea_create`.20- Inferring final capability boundaries during promotion.21- Replacing human review before a promoted idea becomes implementation work.22- Adding dashboard write controls in this change.2324## Decisions2526### Filesystem-backed write tools2728`openspec_idea_create`, `openspec_idea_enrich`, `openspec_idea_promote`, and the task/change lifecycle tools write repo-local markdown directly instead of calling the OpenSpec CLI.2930Alternative considered: shell out to hypothetical CLI commands. Rejected because the current OpenSpec CLI exposes `openspec new change`, not `openspec new idea`, and direct filesystem writes match the existing dashboard scan contract.3132### Explicit lifecycle steps3334Creation, enrichment, and promotion are separate tools. Creation does not automatically enrich or promote.3536Alternative considered: one orchestration tool that creates and enriches in a single call. Rejected because agent/human orchestration needs pause points for review and feedback.3738### Deterministic slugging and collision suffixes3940Idea file names are safe slugs derived from title or an explicit slug. Collisions append `-2`, `-3`, etc. rather than overwriting.4142Alternative considered: timestamps in every slug. Rejected because deterministic human-readable names are easier to inspect and copy.4344### Replaceable enrichment block4546Enrichment uses sentinel comments around a single `## Enrichment Report` block. Re-enriching replaces that block instead of appending duplicates.4748Alternative considered: append every enrichment as history. Rejected for now because the first workflow needs the current report more than audit history.4950### Promotion creates a valid placeholder spec delta5152Promoted ideas create proposal, tasks, metadata, and a placeholder `specs/<change>/spec.md` delta. The placeholder is valid OpenSpec and explicitly says it must be refined before implementation.5354Alternative considered: proposal/tasks only. Rejected because strict OpenSpec validation requires at least one delta, and generated scaffolds should validate immediately.5556## Risks / Trade-offs5758- Placeholder specs can be mistaken for final requirements → Mitigation: wording says they must be refined before implementation.59- Direct filesystem writes bypass future CLI validation rules → Mitigation: outputs are covered by tests and strict OpenSpec validation.60- Registered-source resolution depends on registry availability → Mitigation: explicit `workdir` remains the primary and simplest path.61- Enrichment replacement discards prior report history → Mitigation: acceptable for the first version; history can be added later if needed.6263## Migration Plan6465- Existing OpenSpec repos need no migration.66- New tools create missing `openspec/changes`, `openspec/changes/archive`, `openspec/specs`, and `openspec/ideas` roots as needed.67- Deployment is a normal plugin update/reload; no database migration is required.6869## Open Questions7071- Whether future dashboard UI should expose create/enrich/promote actions directly.72- Whether enrichment should eventually support durable history instead of one replaceable current report.73- Whether promotion should accept explicit capability names once human review has selected affected specs.