bigpowers 2.16.0 → 2.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.pi/package.json +1 -1
- package/.pi/prompts/fix-bug.md +24 -6
- package/.pi/prompts/orchestrate-project.md +8 -0
- package/.pi/prompts/session-state.md +11 -12
- package/.pi/prompts/stocktake-skills.md +24 -1
- package/.pi/skills/fix-bug/SKILL.md +24 -6
- package/.pi/skills/orchestrate-project/SKILL.md +8 -0
- package/.pi/skills/session-state/SKILL.md +11 -12
- package/.pi/skills/stocktake-skills/SKILL.md +24 -1
- package/CHANGELOG.md +14 -0
- package/SKILL-INDEX.md +1 -1
- package/fix-bug/SKILL.md +24 -6
- package/orchestrate-project/SKILL.md +8 -0
- package/package.json +1 -1
- package/scripts/bp-timing.sh +74 -0
- package/session-state/SKILL.md +11 -12
- package/skills-lock.json +4 -4
- package/stocktake-skills/SKILL.md +24 -1
package/.pi/package.json
CHANGED
package/.pi/prompts/fix-bug.md
CHANGED
|
@@ -9,15 +9,33 @@ description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-
|
|
|
9
9
|
|
|
10
10
|
Orchestrates **fix_bug** flow without mixing epic build state.
|
|
11
11
|
|
|
12
|
-
> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug
|
|
12
|
+
> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.
|
|
13
|
+
|
|
14
|
+
## Five steps (`bug_cycle` in state.yaml)
|
|
15
|
+
|
|
16
|
+
| Step | Skill / action |
|
|
17
|
+
|------|----------------|
|
|
18
|
+
| 1 | `investigate-bug` — create BUG-*.md with RCA |
|
|
19
|
+
| 2 | `diagnose-root` — 4-phase root cause analysis |
|
|
20
|
+
| 3 | `develop-tdd` — red-green against bug file verify steps |
|
|
21
|
+
| 4 | `validate-fix` — re-run failing test, full suite, lint |
|
|
22
|
+
| 5 | `release-branch` — PR or solo land the fix |
|
|
23
|
+
|
|
24
|
+
### Checkpoint / resume
|
|
25
|
+
|
|
26
|
+
Track progress via `specs/state.yaml` `bug_cycle`:
|
|
27
|
+
- `bug_cycle.current_step`: current step (1–5)
|
|
28
|
+
- `bug_cycle.completed_steps`: completed step numbers
|
|
29
|
+
- `handoff.next_skill`: skill for the current step
|
|
30
|
+
- On resume, read `bug_cycle.current_step` and continue from there
|
|
13
31
|
|
|
14
32
|
## Process
|
|
15
33
|
|
|
16
|
-
1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file.
|
|
17
|
-
2.
|
|
18
|
-
3. `
|
|
19
|
-
4.
|
|
20
|
-
5. Clear `
|
|
34
|
+
1. **Step 1 — investigate-bug:** If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file. Increment `bug_cycle.current_step` to 2 on completion.
|
|
35
|
+
2. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3.
|
|
36
|
+
3. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green.
|
|
37
|
+
4. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5.
|
|
38
|
+
5. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.
|
|
21
39
|
|
|
22
40
|
## Bug file SoT
|
|
23
41
|
|
|
@@ -31,6 +31,14 @@ claude /orchestrate --mode fast-track
|
|
|
31
31
|
5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: UAT evidence, `specs/EVALS-*.md` if used.
|
|
32
32
|
6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag (vX.Y.Z), `state.yaml` `release.last_tag`.
|
|
33
33
|
|
|
34
|
+
### Checkpoint / resume
|
|
35
|
+
|
|
36
|
+
Track progress via `specs/state.yaml` `project_cycle`:
|
|
37
|
+
- `project_cycle.current_phase`: current phase (1–6)
|
|
38
|
+
- `project_cycle.completed_phases`: completed phase numbers
|
|
39
|
+
- `handoff.next_skill`: skill for the current phase
|
|
40
|
+
- On resume, read `project_cycle.current_phase` and continue from there
|
|
41
|
+
|
|
34
42
|
See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
|
|
35
43
|
|
|
36
44
|
## How Orchestrate Works
|
|
@@ -67,24 +67,23 @@ Whenever a significant decision is made or a milestone is reached:
|
|
|
67
67
|
|
|
68
68
|
→ verify: `bash scripts/validate-specs-yaml.sh`
|
|
69
69
|
|
|
70
|
-
##
|
|
70
|
+
## Universal checkpoint pattern
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
Every multi-step flow (>3 steps) in bigpowers uses a cycle counter in `state.yaml`:
|
|
73
73
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
74
|
+
| Flow | Cycle key | Step field | Phases/Steps |
|
|
75
|
+
|------|-----------|------------|-------------|
|
|
76
|
+
| build-epic | `epic_cycle` | `current_step` | 8 (survey → release) |
|
|
77
|
+
| fix-bug | `bug_cycle` | `current_step` | 5 (investigate → release) |
|
|
78
|
+
| orchestrate-project | `project_cycle` | `current_phase` | 6 (discover → release) |
|
|
77
79
|
|
|
78
|
-
|
|
79
|
-
```yaml
|
|
80
|
-
agent_id: session-state
|
|
81
|
-
acquired_at: "2026-06-11T14:30:00Z"
|
|
82
|
-
```
|
|
80
|
+
**Checkpoint:** After each step/phase completes, increment the counter in `state.yaml` and update `handoff.next_skill`.
|
|
83
81
|
|
|
82
|
+
**Resume:** On session start, read the current step/phase from the cycle key — continue from there, not from step 1.
|
|
84
83
|
|
|
85
|
-
|
|
84
|
+
**Completed steps:** Track completed steps in `completed_steps` (comma-separated string) for audit trail.
|
|
86
85
|
|
|
87
|
-
|
|
86
|
+
## Strategic compaction
|
|
88
87
|
|
|
89
88
|
Print the current session state: `cat specs/state.yaml`, then display `active_flow` and `handoff.next_skill` for quick reference.
|
|
90
89
|
|
|
@@ -21,7 +21,30 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
|
|
|
21
21
|
1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
|
|
22
22
|
2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches.
|
|
23
23
|
3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
|
|
24
|
-
4.
|
|
24
|
+
4. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:
|
|
25
|
+
- Top 5 most-used skills (by calls, total_seconds)
|
|
26
|
+
- Skills with zero calls (potential dead weight)
|
|
27
|
+
- Skills with high average time (candidates for `evolve-skill`)
|
|
28
|
+
5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
|
|
29
|
+
|
|
30
|
+
### Skill timing data (`metrics.skill_timings`)
|
|
31
|
+
|
|
32
|
+
In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
metrics:
|
|
36
|
+
skill_timings:
|
|
37
|
+
survey-context:
|
|
38
|
+
calls: 12
|
|
39
|
+
total_seconds: 180
|
|
40
|
+
avg_seconds: 15.0
|
|
41
|
+
develop-tdd:
|
|
42
|
+
calls: 30
|
|
43
|
+
total_seconds: 5400
|
|
44
|
+
avg_seconds: 180.0
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.
|
|
25
48
|
|
|
26
49
|
## Verify
|
|
27
50
|
|
|
@@ -11,15 +11,33 @@ model: sonnet
|
|
|
11
11
|
|
|
12
12
|
Orchestrates **fix_bug** flow without mixing epic build state.
|
|
13
13
|
|
|
14
|
-
> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug
|
|
14
|
+
> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.
|
|
15
|
+
|
|
16
|
+
## Five steps (`bug_cycle` in state.yaml)
|
|
17
|
+
|
|
18
|
+
| Step | Skill / action |
|
|
19
|
+
|------|----------------|
|
|
20
|
+
| 1 | `investigate-bug` — create BUG-*.md with RCA |
|
|
21
|
+
| 2 | `diagnose-root` — 4-phase root cause analysis |
|
|
22
|
+
| 3 | `develop-tdd` — red-green against bug file verify steps |
|
|
23
|
+
| 4 | `validate-fix` — re-run failing test, full suite, lint |
|
|
24
|
+
| 5 | `release-branch` — PR or solo land the fix |
|
|
25
|
+
|
|
26
|
+
### Checkpoint / resume
|
|
27
|
+
|
|
28
|
+
Track progress via `specs/state.yaml` `bug_cycle`:
|
|
29
|
+
- `bug_cycle.current_step`: current step (1–5)
|
|
30
|
+
- `bug_cycle.completed_steps`: completed step numbers
|
|
31
|
+
- `handoff.next_skill`: skill for the current step
|
|
32
|
+
- On resume, read `bug_cycle.current_step` and continue from there
|
|
15
33
|
|
|
16
34
|
## Process
|
|
17
35
|
|
|
18
|
-
1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file.
|
|
19
|
-
2.
|
|
20
|
-
3. `
|
|
21
|
-
4.
|
|
22
|
-
5. Clear `
|
|
36
|
+
1. **Step 1 — investigate-bug:** If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file. Increment `bug_cycle.current_step` to 2 on completion.
|
|
37
|
+
2. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3.
|
|
38
|
+
3. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green.
|
|
39
|
+
4. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5.
|
|
40
|
+
5. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.
|
|
23
41
|
|
|
24
42
|
## Bug file SoT
|
|
25
43
|
|
|
@@ -33,6 +33,14 @@ claude /orchestrate --mode fast-track
|
|
|
33
33
|
5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: UAT evidence, `specs/EVALS-*.md` if used.
|
|
34
34
|
6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag (vX.Y.Z), `state.yaml` `release.last_tag`.
|
|
35
35
|
|
|
36
|
+
### Checkpoint / resume
|
|
37
|
+
|
|
38
|
+
Track progress via `specs/state.yaml` `project_cycle`:
|
|
39
|
+
- `project_cycle.current_phase`: current phase (1–6)
|
|
40
|
+
- `project_cycle.completed_phases`: completed phase numbers
|
|
41
|
+
- `handoff.next_skill`: skill for the current phase
|
|
42
|
+
- On resume, read `project_cycle.current_phase` and continue from there
|
|
43
|
+
|
|
36
44
|
See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
|
|
37
45
|
|
|
38
46
|
## How Orchestrate Works
|
|
@@ -69,24 +69,23 @@ Whenever a significant decision is made or a milestone is reached:
|
|
|
69
69
|
|
|
70
70
|
→ verify: `bash scripts/validate-specs-yaml.sh`
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## Universal checkpoint pattern
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
Every multi-step flow (>3 steps) in bigpowers uses a cycle counter in `state.yaml`:
|
|
75
75
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
76
|
+
| Flow | Cycle key | Step field | Phases/Steps |
|
|
77
|
+
|------|-----------|------------|-------------|
|
|
78
|
+
| build-epic | `epic_cycle` | `current_step` | 8 (survey → release) |
|
|
79
|
+
| fix-bug | `bug_cycle` | `current_step` | 5 (investigate → release) |
|
|
80
|
+
| orchestrate-project | `project_cycle` | `current_phase` | 6 (discover → release) |
|
|
79
81
|
|
|
80
|
-
|
|
81
|
-
```yaml
|
|
82
|
-
agent_id: session-state
|
|
83
|
-
acquired_at: "2026-06-11T14:30:00Z"
|
|
84
|
-
```
|
|
82
|
+
**Checkpoint:** After each step/phase completes, increment the counter in `state.yaml` and update `handoff.next_skill`.
|
|
85
83
|
|
|
84
|
+
**Resume:** On session start, read the current step/phase from the cycle key — continue from there, not from step 1.
|
|
86
85
|
|
|
87
|
-
|
|
86
|
+
**Completed steps:** Track completed steps in `completed_steps` (comma-separated string) for audit trail.
|
|
88
87
|
|
|
89
|
-
|
|
88
|
+
## Strategic compaction
|
|
90
89
|
|
|
91
90
|
Print the current session state: `cat specs/state.yaml`, then display `active_flow` and `handoff.next_skill` for quick reference.
|
|
92
91
|
|
|
@@ -23,7 +23,30 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
|
|
|
23
23
|
1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
|
|
24
24
|
2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches.
|
|
25
25
|
3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
|
|
26
|
-
4.
|
|
26
|
+
4. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:
|
|
27
|
+
- Top 5 most-used skills (by calls, total_seconds)
|
|
28
|
+
- Skills with zero calls (potential dead weight)
|
|
29
|
+
- Skills with high average time (candidates for `evolve-skill`)
|
|
30
|
+
5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
|
|
31
|
+
|
|
32
|
+
### Skill timing data (`metrics.skill_timings`)
|
|
33
|
+
|
|
34
|
+
In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:
|
|
35
|
+
|
|
36
|
+
```yaml
|
|
37
|
+
metrics:
|
|
38
|
+
skill_timings:
|
|
39
|
+
survey-context:
|
|
40
|
+
calls: 12
|
|
41
|
+
total_seconds: 180
|
|
42
|
+
avg_seconds: 15.0
|
|
43
|
+
develop-tdd:
|
|
44
|
+
calls: 30
|
|
45
|
+
total_seconds: 5400
|
|
46
|
+
avg_seconds: 180.0
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.
|
|
27
50
|
|
|
28
51
|
## Verify
|
|
29
52
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,17 @@
|
|
|
1
|
+
# [2.18.0](https://github.com/danielvm-git/bigpowers/compare/v2.17.0...v2.18.0) (2026-06-21)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Features
|
|
5
|
+
|
|
6
|
+
* **e18s05:** auto-timing helper + stocktake effectiveness ([1542bb7](https://github.com/danielvm-git/bigpowers/commit/1542bb7652c7ba1edb893260c7e586f63e416259))
|
|
7
|
+
|
|
8
|
+
# [2.17.0](https://github.com/danielvm-git/bigpowers/compare/v2.16.0...v2.17.0) (2026-06-21)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Features
|
|
12
|
+
|
|
13
|
+
* **e18s04:** universal checkpoint pattern in fix-bug + orchestrate ([5a47aac](https://github.com/danielvm-git/bigpowers/commit/5a47aac8f0dd1a4463749ab36c64aeded86aa8a4))
|
|
14
|
+
|
|
1
15
|
# [2.16.0](https://github.com/danielvm-git/bigpowers/compare/v2.15.0...v2.16.0) (2026-06-21)
|
|
2
16
|
|
|
3
17
|
|
package/SKILL-INDEX.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
|
|
4
4
|
> Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
|
|
5
5
|
|
|
6
|
-
**Generated:** 2026-06-21T21:
|
|
6
|
+
**Generated:** 2026-06-21T21:42:28Z
|
|
7
7
|
**Skills:** 67
|
|
8
8
|
|
|
9
9
|
---
|
package/fix-bug/SKILL.md
CHANGED
|
@@ -10,15 +10,33 @@ description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-
|
|
|
10
10
|
|
|
11
11
|
Orchestrates **fix_bug** flow without mixing epic build state.
|
|
12
12
|
|
|
13
|
-
> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug
|
|
13
|
+
> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.
|
|
14
|
+
|
|
15
|
+
## Five steps (`bug_cycle` in state.yaml)
|
|
16
|
+
|
|
17
|
+
| Step | Skill / action |
|
|
18
|
+
|------|----------------|
|
|
19
|
+
| 1 | `investigate-bug` — create BUG-*.md with RCA |
|
|
20
|
+
| 2 | `diagnose-root` — 4-phase root cause analysis |
|
|
21
|
+
| 3 | `develop-tdd` — red-green against bug file verify steps |
|
|
22
|
+
| 4 | `validate-fix` — re-run failing test, full suite, lint |
|
|
23
|
+
| 5 | `release-branch` — PR or solo land the fix |
|
|
24
|
+
|
|
25
|
+
### Checkpoint / resume
|
|
26
|
+
|
|
27
|
+
Track progress via `specs/state.yaml` `bug_cycle`:
|
|
28
|
+
- `bug_cycle.current_step`: current step (1–5)
|
|
29
|
+
- `bug_cycle.completed_steps`: completed step numbers
|
|
30
|
+
- `handoff.next_skill`: skill for the current step
|
|
31
|
+
- On resume, read `bug_cycle.current_step` and continue from there
|
|
14
32
|
|
|
15
33
|
## Process
|
|
16
34
|
|
|
17
|
-
1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file.
|
|
18
|
-
2.
|
|
19
|
-
3. `
|
|
20
|
-
4.
|
|
21
|
-
5. Clear `
|
|
35
|
+
1. **Step 1 — investigate-bug:** If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file. Increment `bug_cycle.current_step` to 2 on completion.
|
|
36
|
+
2. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3.
|
|
37
|
+
3. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green.
|
|
38
|
+
4. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5.
|
|
39
|
+
5. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.
|
|
22
40
|
|
|
23
41
|
## Bug file SoT
|
|
24
42
|
|
|
@@ -32,6 +32,14 @@ claude /orchestrate --mode fast-track
|
|
|
32
32
|
5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: UAT evidence, `specs/EVALS-*.md` if used.
|
|
33
33
|
6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag (vX.Y.Z), `state.yaml` `release.last_tag`.
|
|
34
34
|
|
|
35
|
+
### Checkpoint / resume
|
|
36
|
+
|
|
37
|
+
Track progress via `specs/state.yaml` `project_cycle`:
|
|
38
|
+
- `project_cycle.current_phase`: current phase (1–6)
|
|
39
|
+
- `project_cycle.completed_phases`: completed phase numbers
|
|
40
|
+
- `handoff.next_skill`: skill for the current phase
|
|
41
|
+
- On resume, read `project_cycle.current_phase` and continue from there
|
|
42
|
+
|
|
35
43
|
See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
|
|
36
44
|
|
|
37
45
|
## How Orchestrate Works
|
package/package.json
CHANGED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# bp-timing.sh — Record skill invocation timings for stocktake effectiveness analysis.
|
|
3
|
+
# Usage: bash scripts/bp-timing.sh start <skill-name>
|
|
4
|
+
# bash scripts/bp-timing.sh end <skill-name>
|
|
5
|
+
# Requires: python3 (for YAML-safe state updates)
|
|
6
|
+
set -euo pipefail
|
|
7
|
+
|
|
8
|
+
STATE_YAML="specs/state.yaml"
|
|
9
|
+
TIMINGS_KEY="metrics.skill_timings"
|
|
10
|
+
|
|
11
|
+
usage() {
|
|
12
|
+
echo "Usage: $0 start|end <skill-name>" >&2
|
|
13
|
+
exit 1
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
[ $# -ne 2 ] && usage
|
|
17
|
+
|
|
18
|
+
ACTION="$1"
|
|
19
|
+
SKILL="$2"
|
|
20
|
+
|
|
21
|
+
case "$ACTION" in
|
|
22
|
+
start)
|
|
23
|
+
STAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
|
24
|
+
python3 -c "
|
|
25
|
+
import yaml, sys
|
|
26
|
+
try:
|
|
27
|
+
with open('$STATE_YAML') as f:
|
|
28
|
+
data = yaml.safe_load(f) or {}
|
|
29
|
+
except: data = {}
|
|
30
|
+
|
|
31
|
+
metrics = data.setdefault('metrics', {})
|
|
32
|
+
timings = metrics.setdefault('skill_timings', {})
|
|
33
|
+
|
|
34
|
+
if '$SKILL' not in timings:
|
|
35
|
+
timings['$SKILL'] = {'calls': 0, 'total_seconds': 0, 'avg_seconds': 0}
|
|
36
|
+
|
|
37
|
+
timings['$SKILL']['_start'] = '$STAMP'
|
|
38
|
+
with open('$STATE_YAML', 'w') as f:
|
|
39
|
+
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
|
|
40
|
+
" 2>/dev/null || echo "WARN: timing start failed (yaml tools missing?)" >&2
|
|
41
|
+
;;
|
|
42
|
+
|
|
43
|
+
end)
|
|
44
|
+
STAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
|
45
|
+
python3 -c "
|
|
46
|
+
import yaml
|
|
47
|
+
from datetime import datetime
|
|
48
|
+
|
|
49
|
+
with open('$STATE_YAML') as f:
|
|
50
|
+
data = yaml.safe_load(f) or {}
|
|
51
|
+
|
|
52
|
+
metrics = data.setdefault('metrics', {})
|
|
53
|
+
timings = metrics.setdefault('skill_timings', {})
|
|
54
|
+
|
|
55
|
+
if '$SKILL' in timings and '_start' in timings['$SKILL']:
|
|
56
|
+
start_t = datetime.fromisoformat(timings['$SKILL']['_start'].replace('Z','+00:00'))
|
|
57
|
+
end_t = datetime.fromisoformat('$STAMP'.replace('Z','+00:00'))
|
|
58
|
+
elapsed = (end_t - start_t).total_seconds()
|
|
59
|
+
|
|
60
|
+
entry = timings['$SKILL']
|
|
61
|
+
entry['calls'] = entry.get('calls', 0) + 1
|
|
62
|
+
entry['total_seconds'] = entry.get('total_seconds', 0) + elapsed
|
|
63
|
+
entry['avg_seconds'] = entry['total_seconds'] / entry['calls']
|
|
64
|
+
del entry['_start']
|
|
65
|
+
|
|
66
|
+
with open('$STATE_YAML', 'w') as f:
|
|
67
|
+
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
|
|
68
|
+
" 2>/dev/null || echo "WARN: timing end failed" >&2
|
|
69
|
+
;;
|
|
70
|
+
|
|
71
|
+
*)
|
|
72
|
+
usage
|
|
73
|
+
;;
|
|
74
|
+
esac
|
package/session-state/SKILL.md
CHANGED
|
@@ -68,24 +68,23 @@ Whenever a significant decision is made or a milestone is reached:
|
|
|
68
68
|
|
|
69
69
|
→ verify: `bash scripts/validate-specs-yaml.sh`
|
|
70
70
|
|
|
71
|
-
##
|
|
71
|
+
## Universal checkpoint pattern
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
Every multi-step flow (>3 steps) in bigpowers uses a cycle counter in `state.yaml`:
|
|
74
74
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
75
|
+
| Flow | Cycle key | Step field | Phases/Steps |
|
|
76
|
+
|------|-----------|------------|-------------|
|
|
77
|
+
| build-epic | `epic_cycle` | `current_step` | 8 (survey → release) |
|
|
78
|
+
| fix-bug | `bug_cycle` | `current_step` | 5 (investigate → release) |
|
|
79
|
+
| orchestrate-project | `project_cycle` | `current_phase` | 6 (discover → release) |
|
|
78
80
|
|
|
79
|
-
|
|
80
|
-
```yaml
|
|
81
|
-
agent_id: session-state
|
|
82
|
-
acquired_at: "2026-06-11T14:30:00Z"
|
|
83
|
-
```
|
|
81
|
+
**Checkpoint:** After each step/phase completes, increment the counter in `state.yaml` and update `handoff.next_skill`.
|
|
84
82
|
|
|
83
|
+
**Resume:** On session start, read the current step/phase from the cycle key — continue from there, not from step 1.
|
|
85
84
|
|
|
86
|
-
|
|
85
|
+
**Completed steps:** Track completed steps in `completed_steps` (comma-separated string) for audit trail.
|
|
87
86
|
|
|
88
|
-
|
|
87
|
+
## Strategic compaction
|
|
89
88
|
|
|
90
89
|
Print the current session state: `cat specs/state.yaml`, then display `active_flow` and `handoff.next_skill` for quick reference.
|
|
91
90
|
|
package/skills-lock.json
CHANGED
|
@@ -113,7 +113,7 @@
|
|
|
113
113
|
},
|
|
114
114
|
"fix-bug": {
|
|
115
115
|
"description": "Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect.",
|
|
116
|
-
"sha256": "
|
|
116
|
+
"sha256": "aa6fe406ba87a648",
|
|
117
117
|
"path": "fix-bug/SKILL.md"
|
|
118
118
|
},
|
|
119
119
|
"grill-me": {
|
|
@@ -168,7 +168,7 @@
|
|
|
168
168
|
},
|
|
169
169
|
"orchestrate-project": {
|
|
170
170
|
"description": "Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan → build → verify → release) with hard gates. Use to coordinate multi-phase projects with guaranteed quality checkpoints. One-time command for the entire project lifecycle.",
|
|
171
|
-
"sha256": "
|
|
171
|
+
"sha256": "542276f88198ae72",
|
|
172
172
|
"path": "orchestrate-project/SKILL.md"
|
|
173
173
|
},
|
|
174
174
|
"organize-workspace": {
|
|
@@ -248,7 +248,7 @@
|
|
|
248
248
|
},
|
|
249
249
|
"session-state": {
|
|
250
250
|
"description": "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.",
|
|
251
|
-
"sha256": "
|
|
251
|
+
"sha256": "4efd54a453e3e2cd",
|
|
252
252
|
"path": "session-state/SKILL.md"
|
|
253
253
|
},
|
|
254
254
|
"setup-environment": {
|
|
@@ -278,7 +278,7 @@
|
|
|
278
278
|
},
|
|
279
279
|
"stocktake-skills": {
|
|
280
280
|
"description": "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.",
|
|
281
|
-
"sha256": "
|
|
281
|
+
"sha256": "c58bf4f70ff02cd3",
|
|
282
282
|
"path": "stocktake-skills/SKILL.md"
|
|
283
283
|
},
|
|
284
284
|
"survey-context": {
|
|
@@ -22,7 +22,30 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
|
|
|
22
22
|
1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
|
|
23
23
|
2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches.
|
|
24
24
|
3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
|
|
25
|
-
4.
|
|
25
|
+
4. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:
|
|
26
|
+
- Top 5 most-used skills (by calls, total_seconds)
|
|
27
|
+
- Skills with zero calls (potential dead weight)
|
|
28
|
+
- Skills with high average time (candidates for `evolve-skill`)
|
|
29
|
+
5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
|
|
30
|
+
|
|
31
|
+
### Skill timing data (`metrics.skill_timings`)
|
|
32
|
+
|
|
33
|
+
In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:
|
|
34
|
+
|
|
35
|
+
```yaml
|
|
36
|
+
metrics:
|
|
37
|
+
skill_timings:
|
|
38
|
+
survey-context:
|
|
39
|
+
calls: 12
|
|
40
|
+
total_seconds: 180
|
|
41
|
+
avg_seconds: 15.0
|
|
42
|
+
develop-tdd:
|
|
43
|
+
calls: 30
|
|
44
|
+
total_seconds: 5400
|
|
45
|
+
avg_seconds: 180.0
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.
|
|
26
49
|
|
|
27
50
|
## Verify
|
|
28
51
|
|