diff --git a/plugins/numencore-core/skills/decompose/SKILL.md b/plugins/numencore-core/skills/decompose/SKILL.md new file mode 100644 index 0000000..186bcf4 --- /dev/null +++ b/plugins/numencore-core/skills/decompose/SKILL.md @@ -0,0 +1,129 @@ +--- +name: decompose +description: Break a technical specification into atomic, dispatchable task files with dependencies and context assignments. Use when spec/ exists and the project needs an implementation plan. +user-invocable: true +allowed-tools: Read, Write, Bash(mkdir *), Glob, AskUserQuestion +--- + +# Decompose + +You are a task architect. Your job is to read the technical specification and produce a set of atomic, dispatchable task files that an orchestrator can hand to subagents. + +## Prerequisites + +1. Read `./design/spec/overview.md`. If it does not exist, stop and tell the user to run `/spec` first. +2. Read `./design/spec/stack.md`. +3. Read all files in `./design/spec/components/` via glob. +4. Read `./design/state/profile.md` if it exists. + +If any spec file is missing or empty, stop and flag it. + +## Phase 1: Analyze + +1. Build a component inventory from `spec/overview.md`. +2. For each component, read its spec and identify: + - Discrete units of work implied by the interface contract + - Dependencies between components (A's contract references B) + - Natural groupings — work that shares context and should be one task +3. Present a summary to the user: estimated task count per component, identified cross-component dependencies. +4. Ask the user about prioritization preferences — which components should be built first, any sequencing constraints. + +Do not create task files until the user confirms the decomposition approach. + +## Phase 2: Decompose + +For each component, produce task files. Work through one component at a time. + +### Task scoping rules + +- Group related work together. A task implementing all CRUD endpoints for one component is one task, not four. +- A task's declared context files must fit within 80k tokens. Estimate at 3-4 tokens per line of markdown. +- If a task would require understanding multiple unrelated components to implement, it is too broad — split it. +- If a task is so narrow that it uses less than 10% of the context budget, consider merging it with related work. +- Every task must be completable by a single agent in a fresh context window. + +### Task file format + +Write each task to `./design/tasks/.md`: + +```markdown +--- +id: COMP-NNN +component: +depends_on: [] +status: pending +priority: 1 +--- + +# + +## Goal +What the subagent must produce. Be specific — name the files, functions, or modules. + +## Success Criteria +How to verify it is done correctly. Reference specific interface contract lines from the component spec. + +## Context Files +- spec/components/.md +- spec/stack.md + +## Constraints +Anything the subagent must respect. +``` + +### ID conventions + +- Prefix is the component ID, uppercase: `AUTH`, `DB`, `API` +- Suffix is a three-digit sequence: `001`, `002`, `003` +- IDs are globally unique across all components + +### Dependency rules + +- `depends_on` contains task IDs, not component names +- Every referenced ID must exist in another task file +- Dependencies must form a DAG — no cycles +- When component A's interface consumes component B, the task implementing B's interface must precede A's integration task + +### Priority rules + +- Lower number = higher priority +- User sequencing preferences from Phase 1 override default priority +- Within a component, foundation tasks (data models, core interfaces) precede integration tasks +- Tasks with no dependencies get the highest priority in their component + +## Phase 3: Progress State + +After all task files are written, create `./design/state/progress.md`: + +```markdown +# Progress + +## Phase +decomposed + +## Task Index +| ID | Component | Title | Priority | Depends On | Status | +|----|-----------|-------|----------|------------|--------| + +## Dependency Graph +``` + +``` +``` + +## Phase 4: Present + +1. Present the full task index table to the user. +2. Highlight the critical path — the longest dependency chain. +3. Identify parallel groups — tasks with no shared dependencies that can execute concurrently. +4. Wait for confirmation or revision requests. +5. On confirmation, create all directories and write all files. + +## Constraints + +- Do not invent requirements not present in the spec. Decompose translates, it does not design. +- Do not create tasks without user confirmation of the decomposition approach. +- Success criteria must reference specific interface contract lines — not vague outcomes like "works correctly." +- Context files must be paths that exist in `./design/`. Do not reference files that have not been written. +- Every component in the spec must have at least one task. Flag if a component seems to need zero tasks. +- Zero dangling dependency references. Every ID in `depends_on` must match an existing task's `id`. diff --git a/plugins/numencore-core/skills/plan-check/SKILL.md b/plugins/numencore-core/skills/plan-check/SKILL.md new file mode 100644 index 0000000..d9dfd62 --- /dev/null +++ b/plugins/numencore-core/skills/plan-check/SKILL.md @@ -0,0 +1,118 @@ +--- +name: plan-check +description: Validate decomposed task plan for dependency cycles, scope conflicts, context budget, and contract coverage. Use after /decompose and before orchestrator dispatch. +user-invocable: true +allowed-tools: Read, Write, Glob, Grep +--- + +# Plan Check + +You are a plan validator. Your job is to verify that the decomposed task plan is sound before the orchestrator begins execution. + +## Prerequisites + +1. Glob `./design/tasks/*.md`. If no task files exist, stop and tell the user to run `/decompose` first. +2. Read `./design/spec/overview.md`. +3. Read all files in `./design/spec/components/` via glob. +4. Read `./design/state/progress.md`. + +## Validation Checks + +Run all checks. Do not stop at the first failure — collect all issues. + +### Check 1: Dependency Graph Integrity + +1. Parse `depends_on` from every task file's frontmatter. +2. Build the full adjacency list. +3. Verify the graph is a DAG — detect any cycles. +4. Verify every ID in `depends_on` references an existing task. +5. Cycle or dangling reference = **error**. + +### Check 2: Component Coverage + +1. Read the component inventory from `spec/overview.md`. +2. Verify every component has at least one task. +3. Missing component = **error**. + +### Check 3: Contract Coverage + +1. For each component spec in `spec/components/`, read section 9 (Interface Contract). +2. For each contract line, verify at least one task's success criteria references it. +3. Unaddressed contract line = **error**. + +### Check 4: Context Budget + +1. For each task, read its Context Files list. +2. For each referenced file, count lines. Estimate tokens at 3-4 tokens per line. +3. Sum per task. Flag any task exceeding 80k tokens. +4. Budget exceeded = **error**. + +### Check 5: Parallel Safety + +1. Identify task groups that have no dependency relationship — candidates for parallel dispatch. +2. For each parallel group, check if any tasks write to the same component. +3. Same-component parallel writes = **warning**. + +### Check 6: Context File Existence + +1. For each task, verify every path in Context Files exists in `./design/`. +2. Missing file = **error**. + +## Output + +Write the validation report to `./design/state/plan-check.md`. + +### Pass format + +```markdown +# Plan Validation Report + +## Status +pass + +## Critical Path +COMP-NNN → COMP-NNN → COMP-NNN + +## Parallel Groups +- [COMP-NNN, COMP-NNN] — no shared boundaries +- [COMP-NNN, COMP-NNN] — no shared boundaries + +## Task Count +N tasks across M components + +## Context Budget +All tasks within 80k limit. Largest: COMP-NNN at ~Nk. +``` + +### Fail format + +```markdown +# Plan Validation Report + +## Status +fail — N errors, M warnings + +## Errors + +### ERR-001: + +**Impact:** +**Fix:** + +## Warnings + +### WARN-001: + +**Impact:** +**Fix:** +``` + +Every error has: what is wrong, what breaks, how to fix it. Warnings follow the same format but are non-blocking. + +## Constraints + +- Read-only with respect to spec files. Never modify specs. +- May fix mechanical task issues: typos in dependency references, missing frontmatter fields. Must not restructure tasks. +- Complete validation in a single pass. Either the plan passes or it does not. +- If the plan fails, do not proceed. Present the report and tell the user to revise via `/decompose` or manual edits. +- If the plan passes, confirm to the user that the plan is cleared for orchestrator dispatch.