phatch/numencore-toolkit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(numencore-core): add decompose and plan-check skills

Browse source 
- decompose breaks specs into atomic task files with dependencies
- plan-check validates the task plan before orchestrator dispatch
This commit is contained in:
Parley Hatch 2026-03-19 23:42:46 -06:00
parent 85b682e6a9
commit 9d0b23eca1
2 changed files with 247 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

129
plugins/numencore-core/skills/decompose/SKILL.md Normal file
View file

@ -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/<COMP-NNN>.md`:
```markdown
---
id: COMP-NNN
component: <component-id>
depends_on: []
status: pending
priority: 1
---
# <Task title>
## 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/<relevant>.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
```
<adjacency list>
```
```
## 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`.

118
plugins/numencore-core/skills/plan-check/SKILL.md Normal file
View file

@ -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: <category>
<What is wrong — specific tasks, IDs, or contract lines involved>
**Impact:** <What breaks if this is ignored>
**Fix:** <Actionable recommendation>
## Warnings
### WARN-001: <category>
<What is wrong>
**Impact:** <What could go wrong>
**Fix:** <Actionable recommendation>
```
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.