gcf-aif-ext 0.32.0 → 0.36.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/README.md +45 -6
- package/commands/gcf.js +344 -82
- package/extension.json +1 -1
- package/injections/plan-context.md +3 -0
- package/lib/agent-permissions.js +28 -4
- package/lib/audit-core.js +72 -127
- package/lib/board.js +22 -10
- package/lib/changes.js +7 -1
- package/lib/commit-files.js +1 -0
- package/lib/commit-move.js +56 -10
- package/lib/config-set.js +52 -14
- package/lib/context.js +29 -16
- package/lib/d2-states.js +208 -0
- package/lib/design-parts.js +37 -7
- package/lib/domain.js +144 -11
- package/lib/gcf-paths.js +13 -2
- package/lib/git.js +62 -17
- package/lib/inbox-categories.js +3 -0
- package/lib/inbox.js +69 -4
- package/lib/lessons.js +133 -4
- package/lib/main-lock.js +195 -3
- package/lib/plan-check.js +339 -37
- package/lib/play.js +21 -20
- package/lib/review.js +111 -2
- package/lib/rules.js +428 -0
- package/lib/session-mark.js +2 -1
- package/lib/systems-doc.js +60 -13
- package/lib/validate-item.js +9 -0
- package/lib/work-ops.js +109 -50
- package/package.json +1 -1
- package/profiles/plan.md +1 -1
- package/schemas/item.schema.json +4 -0
- package/skills/gcf-audit/SKILL.md +10 -5
- package/skills/gcf-card/SKILL.md +12 -10
- package/skills/gcf-chat/SKILL.md +14 -10
- package/skills/gcf-triage/SKILL.md +19 -1
- package/skills/gcf-verdict/SKILL.md +7 -5
- package/templates/agents-block.md +23 -2
- package/templates/config.yml +10 -6
|
@@ -7,6 +7,7 @@ mode: human gate
|
|
|
7
7
|
|
|
8
8
|
purpose:
|
|
9
9
|
- turn raw input into decided work: each inbox entry becomes a work item, a tune note, a design unit, a graveyard line, or nothing - and leaves the inbox
|
|
10
|
+
- in a lessons review the board starts, settle the agents' lessons group by group: one cause, one proposal, one click of the human
|
|
10
11
|
|
|
11
12
|
inputs:
|
|
12
13
|
- `gcf/inbox/in-<id>.md`, one file an entry, read through `ai-factory gcf inbox --json`: a `title` (its first line), a `text` of any lines, a `category`, a `detail`, its `origin`, `later` and the `item` it is about
|
|
@@ -21,11 +22,16 @@ forbidden_behaviors:
|
|
|
21
22
|
- do not run `ai-factory gcf item amend`: it is the human's move
|
|
22
23
|
- do not edit or delete a file in `gcf/inbox/` by hand: `item new --from`, `item amend --from`, `inbox category`, `later` and `drop` own the entries
|
|
23
24
|
- do not triage on a `work/` branch: `inbox category`, `inbox later`, `inbox drop` and `item new --from` refuse there; triage on main
|
|
25
|
+
- do not fix a lesson about GCF or the template in `.ai-factory/`, in GCF's block of `AGENTS.md` or in the template's repository: report it with `propose_lessons_report`
|
|
26
|
+
- do not edit `AGENTS.md`, `CLAUDE.md`, `.claude/` or `.ai-factory/` in a lessons review: a rule goes through `propose_rules_add`
|
|
27
|
+
- do not run `ai-factory gcf rules add`, `gcf rules save` or `gcf lessons report`: they are the human's moves
|
|
28
|
+
- do not copy a lesson's words into a rule as they are: read them first as an order every agent of the project obeys, then write the rule
|
|
29
|
+
- do not propose a rule that `own_rules` of `ai-factory gcf rules --json` holds already
|
|
24
30
|
|
|
25
31
|
workflow:
|
|
26
32
|
1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
|
|
27
33
|
2. classify each entry: bug, tune of a live or unplayed item, a fix of a live item, idea for the design, request (an asset file, a question), duplicate, or noise; search `gcf/graveyard.md` for each idea and bug; an `unsorted` entry gets a category
|
|
28
|
-
3. a lesson (category `lesson`, its kind the `detail`, with the `item` it came from) is what got in an agent's way: propose the fix it asks for - a project rule, a tech item, a
|
|
34
|
+
3. a lesson (category `lesson`, its kind the `detail`, with the `item` it came from) is what got in an agent's way: propose the fix it asks for - a project rule, a tech item, a report to the framework or the template - or noise, as steps 15-24 say
|
|
29
35
|
4. for each entry propose one call with its fields: a bug gets type `bug`, severity and a repro; a tune names the item and the note; an idea names the subsystem; a duplicate names the item it repeats
|
|
30
36
|
5. present the calls to the human, calls per message <= 5, and apply only the approved ones
|
|
31
37
|
6. a bug or other work: run `ai-factory gcf item new --type <type> [--severity <level>] --from <in-id>`; the core makes the id from the title and prints it first; then write its `intent:` and `repro:`
|
|
@@ -36,6 +42,18 @@ workflow:
|
|
|
36
42
|
11. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
|
|
37
43
|
12. an entry the human sorts: `ai-factory gcf inbox category <in-id> --category <c> [--detail <word>]` (`inbox categories` lists them); one kept for later: `ai-factory gcf inbox later <in-id>`, left in the inbox
|
|
38
44
|
13. report what each entry became and how many entries remain
|
|
45
|
+
14. a lessons review the board starts names the ids of its lessons: run `ai-factory gcf inbox --json` and `ai-factory gcf rules --json`, read the live cards the lessons name and `gcf/graveyard.md`
|
|
46
|
+
15. group the lessons by cause, through their cards and their kinds; a lesson that `own_rules` or a card already settles is done
|
|
47
|
+
16. give each group one outcome: a new item, a fix of a live card, a rule, a report, an erase or Later; done and noise lessons of other causes go together as one erase by reason
|
|
48
|
+
17. groups per message <= 5; each group gets one line of what got in the agent's way and one proposal
|
|
49
|
+
18. a new item: `propose_item_new` with every id of the group in `from`; a fix of a live card: `propose_amend` with its `id` and the group in `from`
|
|
50
|
+
19. an item that improves the project's base is type `tech`; its note has `improves:` (rule-check, diagnostic, library, tool or architecture) and `lessons:` (the ids, their words, the `file:line`)
|
|
51
|
+
20. that note also has `change:` (what to build, in the project's words) and `done when:` (the project's DoD command that shows it)
|
|
52
|
+
21. a `library` or `architecture` change goes with the gate `verdict`; the other changes take the gate of their type
|
|
53
|
+
22. a rule: `propose_rules_add` with one line in `language.ui` in `text` and the group in `from`
|
|
54
|
+
23. a lesson about GCF or the template (kind `framework` or `template`): `propose_lessons_report` with the group in `from` and `to` as `framework` or `template`
|
|
55
|
+
24. an erase: `propose_inbox_drop` with the group in `ids`, its `reason` (`done`, `duplicate` or `noise`) and `of` for the card, entry or commit; Later: `propose_inbox_later` with the group in `ids`
|
|
56
|
+
25. the human splits a group in words ("separate in-a"): propose its parts again; when the human says next, go on with the next groups
|
|
39
57
|
|
|
40
58
|
invocation:
|
|
41
59
|
- run after a playtest session, after a CI run that added entries, or when the user asks to triage
|
|
@@ -34,11 +34,13 @@ workflow:
|
|
|
34
34
|
4. for `keep` of a design-unit item still awaiting its verdict: compress it first - the collapse copies lines verbatim, 1 line per behavior record, refusal and boundary
|
|
35
35
|
5. for that keep: strip `contract:` down to paths and entry points and cut `intent:` to the line the subsystem's purpose still lacks; leave an unplayed item as it is - its close froze the body
|
|
36
36
|
6. run `ai-factory gcf verdict <id> <verdict> --note "<answer>"`, with `--played-on <build>` per build of `play.builds` the human played on; a kill makes a removal item for code in main unless `--no-remove`
|
|
37
|
-
7.
|
|
38
|
-
8.
|
|
39
|
-
9. for
|
|
40
|
-
10.
|
|
41
|
-
11.
|
|
37
|
+
7. after each verdict - step 6, or the milestone keep of step 13 - run `ai-factory gcf audit --json`
|
|
38
|
+
8. each stale `until` entry the verdict fired - `verdict(<id>)` of the item or of each id the milestone keep prints after `→`, or `retune(<its subsystem>)` after a tune - ask the human now, while present, as steps 4-8 of the gcf-audit skill do
|
|
39
|
+
9. for a decision run `ai-factory gcf decide <id> <choice> --reason "<why>"`; `known` parks a bug and lists it in `gcf/LIVE.md` known issues
|
|
40
|
+
10. for a feature whose child died, the human picks: `close` without the child, `continue` with a replacement, or `kill` with its live children
|
|
41
|
+
11. for `keep` on an item touching 2 or more subsystems: read each updated systems doc and report a contradiction between constraints as a D1 question instead of finishing silently
|
|
42
|
+
12. report the commit hash, `git revert <hash>` undoes that one move - not the code, nor a later move or edit on the same files - and the id of any removal item the command made
|
|
43
|
+
13. a whole milestone: compress its awaiting-verdict units as in steps 4-5, then run `ai-factory gcf verdict <milestone> keep --milestone`
|
|
42
44
|
|
|
43
45
|
invocation:
|
|
44
46
|
- run after a playtest session, on a human decision, or with no arguments to print the playtest sheet
|
|
@@ -3,6 +3,8 @@ gcf_context:
|
|
|
3
3
|
- read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
|
|
4
4
|
- `gcf/LIVE.md` says what the game does now, and `gcf/PILLARS.md` says what it must stay
|
|
5
5
|
- `ai-factory gcf board --json` gives the whole state in one read: the phase, the items by status with plan progress, the inbox and the open questions
|
|
6
|
+
- start a session with `ai-factory gcf audit` and state its first line before anything else
|
|
7
|
+
- a stale `until` record that line names goes to the human through the gcf-audit skill: the human confirms or replaces the value
|
|
6
8
|
|
|
7
9
|
gcf_work:
|
|
8
10
|
- every piece of work is one work item `gcf/work/<id>.md`: find the item before writing code for a feature, a bug or a tech task, or create it with the gcf-card skill
|
|
@@ -18,7 +20,10 @@ gcf_work:
|
|
|
18
20
|
- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
|
|
19
21
|
- an item's plan is in the plan form: blocks `context:`, `decisions:` (records `id`, `pick`, `why`), `tasks:` (`- [ ] t1 <action> (d1)`), `pillar_check:`, `verification:`, one idea a line
|
|
20
22
|
- `ai-factory gcf plan check <id>` lists the plan's form problems as `format:` lines: fix them, they never block
|
|
21
|
-
-
|
|
23
|
+
- in a plan review the reviewer only finds; you, the plan's author, check each finding against the code, give it a verdict (`accepted`; `rejected` or `downgraded` with a `reason`) and fix the plan
|
|
24
|
+
- record the pass with `ai-factory gcf plan pass <id> --findings <file.json> --json`; its verdict decides: continue, converged or stalled
|
|
25
|
+
- `gcf review row … --kind plan` also gives `mode`: `full` is the whole plan, `check` the fixes by the diff since the earlier pass; ask only the next pass; a blocking finding needs a `scenario`
|
|
26
|
+
- record a code review's pass with `--kind code --blocking <n> --polish <m>`
|
|
22
27
|
- `ai-factory gcf review row <id> --kind plan|code --pass <k> --json` names who makes review pass k, by `review.plan|code` of `gcf/config.yml`, and its `fallback`: the stand-ins in order when that row cannot make the pass
|
|
23
28
|
- a pass a stand-in or you made records both: `ai-factory gcf plan pass <id> … --by <who made it> --for <the row>`
|
|
24
29
|
- a `stalled` verdict: `ai-factory gcf review stall <id> --kind plan|code --passes <counts>` blocks the card
|
|
@@ -46,6 +51,10 @@ gcf_work:
|
|
|
46
51
|
- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
|
|
47
52
|
- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:` and new inbox entries, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
|
|
48
53
|
- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
|
|
54
|
+
- a fired assumption is never an inbox entry
|
|
55
|
+
- a fired D2 is not re-filed as a D1: the human answers its own record; a plan that needs its value blocks with `--reason "needs the human's answer to <q-NNN> (its until fired)"`
|
|
56
|
+
- an assumption with no record, a fired inline `until` annotation or a belief your work shows false, is a D1 question
|
|
57
|
+
- file it with `ai-factory gcf question add --class D1 --question "<question>" --proposed "<your answer>"`, and `--blocks <id>` for the item it holds
|
|
49
58
|
- name each thing by the term `GLOSSARY.md` defines for it
|
|
50
59
|
- a word added to an `avoid:` of `GLOSSARY.md` leaves `gcf/design/`, `gcf/systems/`, `gcf/PILLARS.md` and every item but an unplayed one in the same commit
|
|
51
60
|
- `ai-factory gcf design check` names each hit of an avoided word in design and items as M4, `npx --yes cnlp-kit check` the rest
|
|
@@ -102,6 +111,8 @@ gcf_work:
|
|
|
102
111
|
- an answer that moves into a unit's slot goes there in English
|
|
103
112
|
- do not translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `planning does not converge`, `waits for`)
|
|
104
113
|
- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
|
|
114
|
+
- a D2 record's `answer:` from the human overrules its `assumed:`: write it into each slot that cites `assumed: q-NNN`, cite `answer: q-NNN` there, then remove the record
|
|
115
|
+
- an unplayed item's body is frozen: its `assumed: q-NNN` stays, and the answered record stays while an unplayed item cites it; it leaves after that item's verdict
|
|
105
116
|
- a pillar changes only on the human's word; its short `name:` is what the human knows it by, and its id comes from the name
|
|
106
117
|
- a new name saved with `design save` renames the id in every file that cites it
|
|
107
118
|
- `ai-factory gcf pillar retire <id> --reason "<why>"` takes a pillar out
|
|
@@ -113,14 +124,23 @@ gcf_work:
|
|
|
113
124
|
- a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know; a note <= 4000 characters
|
|
114
125
|
- in the project chat (the gcf-chat skill) propose a new item with the `propose_item_new` tool of the `gcf` MCP server, not with `item new`: the human's click makes it
|
|
115
126
|
- a decision about a live item goes into its card with the human's `ai-factory gcf item amend <id>`, never into the inbox or a new item, which a run does not read
|
|
116
|
-
- its `--text` replaces the blocks it names, `--add` adds to `notes:`; `--title` and `--from <in-
|
|
127
|
+
- its `--text` replaces the blocks it names, `--add` adds to `notes:`; `--title` and `--from <in-ids>` go with them
|
|
117
128
|
- a decision that contradicts a slot replaces the slot through `--text`; a run that finds a `notes:` line against a slot builds by the note and rewrites that slot of its own card
|
|
118
129
|
- in the project chat propose these with their `propose_` tools and the `id` they act on: an amend, a block, a drop, a dependency change, an unblock, a verdict, a decision, an answer to an open question
|
|
119
130
|
- so are the inbox's add, category, Later and erase
|
|
131
|
+
- several inbox entries of one cause go as one move and one commit: `--from in-a,in-b` of `item new` and `item amend` (a bullet each in the note), `inbox later in-a in-b`
|
|
132
|
+
- an erase says why: `inbox drop in-a in-b --reason done|duplicate|noise|reported|amended [--of <id|hash>]`
|
|
133
|
+
- their proposals take `from` or `ids`, an erase its `reason` and `of`
|
|
120
134
|
- the human's click makes each of those proposals
|
|
135
|
+
- the project's own rules for its agents are lines under `## Project rules` of `AGENTS.md`, outside this block: `ai-factory gcf rules --json` reads them and both files
|
|
136
|
+
- `gcf rules add` and `gcf rules save` are the human's moves; in the project chat propose a rule with `propose_rules_add`: one line in `language.ui`
|
|
137
|
+
- `gcf rules diff --from <hash> --to <hash> --json` shows what commits changed in the agent's instructions: `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.ai-factory/` outside its plans and archive
|
|
138
|
+
- a lesson about GCF or the template goes to the human's `gcf lessons report --to framework|template`, proposed with `propose_lessons_report`; never fix it in `.ai-factory/`, in this block or in the template
|
|
139
|
+
- a tech item that improves the project's base (a rule check, a diagnostic, a library, a tool, the architecture) has a note with `improves:`, `lessons:`, `change:` and `done when:`
|
|
121
140
|
- in the project chat propose a new item by its title, never an id
|
|
122
141
|
- in the project chat propose a verdict only after the human said in the talk that they played the item and how it felt, its note in the human's words; leave the `remove` of a kill, a no or a wontfix to the rule unless the human says otherwise
|
|
123
142
|
- a move refused for hand edits under `gcf/` ends its error with `gcf-refusal: {"code":"dirty","paths":[…]}`: `ai-factory gcf edits diff --path <path>` shows them; `gcf edits commit` and `gcf edits discard` are the human's moves, never the agent's
|
|
143
|
+
- while a main run works a card, your move is still refused for that run's `gcf/` edits and does not wait; the human's move waits behind the run: propose the move to the human, or make it again after the card's commit
|
|
124
144
|
- `item amend` refused for a live run ends with `gcf-refusal: {"code":"running"}`, and refused for a card changed since its preview with `gcf-refusal: {"code":"stale"}`
|
|
125
145
|
- a move the commit gate refuses ends its error with `gcf-refusal: {"code":"gate","problems":[…]}`: git holds no commit of it; fix what it names, then make the move again
|
|
126
146
|
- `ai-factory gcf changes [--worktree <id>]` lists what is uncommitted in the checkout or an item's worktree, `gcf changes diff --path <path>` shows one text file's diff
|
|
@@ -136,6 +156,7 @@ gcf_forbidden:
|
|
|
136
156
|
- do not give a verdict: `verdict` belongs to the human, through the gcf-verdict skill; nor a decision, but `go` or `no` of the spike you drive when the gates say `decision: agent`
|
|
137
157
|
- the core refuses the human's moves to a harness run and a board chat: bring the move to the human, or block the item with the question
|
|
138
158
|
- those moves are `verdict`, `decide`, `drop` of a work item, `unblock`, `item amend`, `question answer`, `config set`, `playtest setup`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`, `changes commit`
|
|
159
|
+
- so are `rules add`, `rules save` and `lessons report`
|
|
139
160
|
- a run's agent does not build the game to play nor start a player: the harness builds it at the run's end, and `dod.build` only checks the code
|
|
140
161
|
- in the project chat, when the human asks for a build, run `ai-factory gcf playtest build <id>` or `ai-factory gcf playtest build --main` yourself
|
|
141
162
|
- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
|
package/templates/config.yml
CHANGED
|
@@ -25,15 +25,19 @@ auto_compact_pct: 0
|
|
|
25
25
|
# ask: d1
|
|
26
26
|
# answer_timeout_min: 15
|
|
27
27
|
# The review passes of a plan and of the code before its commit (Operator-Tasks-Plan t2): row k
|
|
28
|
-
# makes pass k (agent claude or codex; a Claude model alias, a Codex family or slug; an effort)
|
|
29
|
-
#
|
|
30
|
-
#
|
|
31
|
-
#
|
|
32
|
-
#
|
|
28
|
+
# makes pass k (agent claude or codex; a Claude model alias, a Codex family or slug; an effort).
|
|
29
|
+
# A plan pass reviews the whole plan when no pass has seen it yet (its first pass, or a plan from
|
|
30
|
+
# before this rule), else it checks only the author's fixes since the last pass seen, a new cycle
|
|
31
|
+
# after an amend too. A pass goes on while the last one left a blocking finding, accepted,
|
|
32
|
+
# rejected or downgraded; the rows over, the card blocks for you. An empty list: no review. Row 1
|
|
33
|
+
# of the plan goes on high effort: it makes a new plan's full review. A row that cannot make its
|
|
34
|
+
# pass (no Codex, its limit, a failure) gives way to a model of its size: Codex medium to Fable
|
|
35
|
+
# medium then Opus high, Codex high and Fable medium to Opus high. Uncomment to change, or set it
|
|
36
|
+
# in Settings
|
|
33
37
|
# (ai-factory gcf config set review.plan --value "claude:opus:high, codex:astra:medium"):
|
|
34
38
|
# review:
|
|
35
39
|
# plan:
|
|
36
|
-
# - {agent: codex, model: astra, effort:
|
|
40
|
+
# - {agent: codex, model: astra, effort: high}
|
|
37
41
|
# - {agent: claude, model: fable, effort: medium}
|
|
38
42
|
# - {agent: claude, model: fable, effort: medium}
|
|
39
43
|
# code:
|