UNPKG

paqad-ai

Version:

Spec-driven development framework — AI agents that think before they type

github.com/Eliyce/paqad-ai

Eliyce/paqad-ai

56 lines (40 loc) • 3.12 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
--- name: context-budget-planner description: "Estimates the implementation phase's token footprint from spec, test plan and affected files, and recommends compaction before context runs out. Use when a graduated or full lane change moves from planning to implementation." metadata: model_tier: fast cacheable: 'false' output_format: markdown paqad-meta: skill.meta.yaml --- ## What It Does Predicts the token footprint of the upcoming implementation phase before it starts. Reads spec size, test plan size, affected module docs, and known changed files; sums their token cost using the per-line weights in the heuristics reference; compares against the available budget; and recommends compaction when the estimate would push the session into the Amber or Red tier. The point is to catch starvation before it happens, not after compaction has already evicted decisions mid-task. ## Use This When Once at the boundary between planning and implementation in the graduated and full lanes: after acceptance criteria and test plan exist, before the first source file is opened. Skip in the fast lane; the overhead is not justified for low-complexity work. ## Inputs - Read the active spec at `spec_path` first. - Read `test_plan_path` when supplied. - Read each module doc in `affected_module_doc_paths` only enough to compute its line count. - Read `references/budget-heuristics.md` before applying any threshold so the per-line weights and tier boundaries stay consistent across runs. ## Procedure 1. Determine the project's model context window (from project profile) and committed tokens (default 200000 / 30000 if not declared). 2. Pick per-line weights from `references/budget-heuristics.md` (or `assets/weights.default.txt` if the project has none yet). 3. Pipe `<weight> <path>` rows into `scripts/estimate-tokens.sh --available <N> --committed <N>`: it line-counts, multiplies, sums, picks the tier, and emits the markdown block. 4. When the script reports Amber or Red, fill the compaction list using the priority order from `references/budget-heuristics.md`. 5. Validate the final output with `scripts/lint-output.sh`. ## Output Contract - Match `assets/output.template.md`: `## Context Budget`, single `Summary:` line, `### Per-Artifact Estimate` table, `### Recommended Compactions`. - Green/Yellow → `Recommended Compactions: none` exactly. Amber/Red → ordered list with one-line reasons. - Output must pass `scripts/lint-output.sh` (exit 0). ## Escalate / Stop Conditions - Ask when the project profile declares no model context window and the default would clearly overcommit. - Warn when `Tier: red` is reached even after applying every available compaction: implementation should be split into smaller stories rather than starting with no headroom. - Do not recommend evicting the active spec, the rules constitution, the project profile, or the active decision packet under any tier. ## Resources - `references/budget-heuristics.md` - `scripts/estimate-tokens.sh` - `scripts/lint-output.sh` - `assets/output.template.md` - `assets/weights.default.txt` - `agents/openai.yaml`