gcf-aif-ext 0.22.0 → 0.23.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 +19 -2
- package/commands/gcf.js +67 -0
- package/extension.json +1 -1
- package/lib/agent-permissions.js +18 -10
- package/lib/audit-core.js +2 -1
- package/lib/changes.js +26 -7
- package/lib/design-parts.js +13 -5
- package/lib/domain.js +35 -4
- package/lib/git.js +8 -1
- package/lib/id.js +1 -0
- package/lib/inbox-categories.js +1 -0
- package/lib/inbox.js +6 -1
- package/lib/integrate.js +76 -16
- package/lib/lessons.js +2 -1
- package/lib/main-lock.js +1 -1
- package/lib/migrate.js +1 -0
- package/lib/milestone-state.js +2 -1
- package/lib/systems-doc.js +50 -2
- package/lib/transitions.js +2 -0
- package/lib/work-ops.js +201 -8
- package/package.json +1 -1
- package/skills/gcf-chat/SKILL.md +16 -9
- package/skills/gcf-triage/SKILL.md +9 -7
- package/templates/agents-block.md +55 -23
|
@@ -18,22 +18,24 @@ forbidden_behaviors:
|
|
|
18
18
|
- do not create an item or erase an entry without the human's yes: the agent proposes, the human approves
|
|
19
19
|
- do not turn a feel complaint into a bug: "jump feels floaty" is a tune of the item that owns the jump, a bug is behaviour that breaks a rule or a test
|
|
20
20
|
- do not open a second item for something `gcf/graveyard.md` already buried: name the line and ask whether the reason still holds
|
|
21
|
-
- do not
|
|
21
|
+
- do not run `ai-factory gcf item amend`: it is the human's move
|
|
22
|
+
- 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
|
|
22
23
|
- do not triage on a `work/` branch: `inbox category`, `inbox later`, `inbox drop` and `item new --from` refuse there; triage on main
|
|
23
24
|
|
|
24
25
|
workflow:
|
|
25
26
|
1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
|
|
26
|
-
2. classify each entry: bug, tune of a live or unplayed 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
|
|
27
|
+
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
|
|
27
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 note for the framework or the template - or noise
|
|
28
29
|
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
|
|
29
30
|
5. present the calls to the human, calls per message <= 5, and apply only the approved ones
|
|
30
31
|
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:`
|
|
31
32
|
7. `--from` without `--title` makes the entry's title the item's title and puts the rest of its text in a `note:` block, its pictures in `gcf/work/<id>/attachments/`; with your own `--title` the whole text goes into `note:`
|
|
32
|
-
8. a
|
|
33
|
-
9. an
|
|
34
|
-
10.
|
|
35
|
-
11.
|
|
36
|
-
12.
|
|
33
|
+
8. a fix of a live item's text: in the board's chat call `propose_amend` with its `id` and `from`; in a console give the human the line `ai-factory gcf item amend <id> --from <in-id>` to run
|
|
34
|
+
9. a tune of an item waiting for its verdict or unplayed: leave the entry in the inbox, the note's only copy, until `/gcf-verdict <id> tune --note` records it and drops it; a tune of a kept mechanic is new work with `--reopens <id>`
|
|
35
|
+
10. an idea for the design: write a unit with `TBD` slots in `gcf/design/<system>.md` and its backlog line, then run `ai-factory gcf inbox drop <in-id>`
|
|
36
|
+
11. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
|
|
37
|
+
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
|
+
13. report what each entry became and how many entries remain
|
|
37
39
|
|
|
38
40
|
invocation:
|
|
39
41
|
- run after a playtest session, after a CI run that added entries, or when the user asks to triage
|
|
@@ -6,60 +6,92 @@ gcf_context:
|
|
|
6
6
|
|
|
7
7
|
gcf_work:
|
|
8
8
|
- 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
|
|
9
|
-
- an id is the system's: `ai-factory gcf item new --title "<title>" --type <type>` makes it from the title and prints it first
|
|
10
|
-
-
|
|
11
|
-
- an
|
|
9
|
+
- an id is the system's: `ai-factory gcf item new --title "<title>" --type <type>` makes it from the title and prints it first
|
|
10
|
+
- name an item or a unit to the human by its title with the id in brackets, "double jump (dvoinoi-pryzhok)"
|
|
11
|
+
- an id you write by hand in a file (a unit of an interview, a pillar) follows the same rule: the title in Latin lowercase, words <= 4 joined by hyphens, `-2` when taken
|
|
12
|
+
- input that is not work yet goes to `ai-factory gcf inbox add "<text>" --category <category> [--detail <word>] [--item <id>]` (an entry `gcf/inbox/in-<id>.md`), and the gcf-triage skill sorts it later
|
|
13
|
+
- a text that starts with a hyphen goes as `inbox add --text="<text>"`
|
|
14
|
+
- an agent names the category: `ai-factory gcf inbox categories` lists them and who may file each
|
|
15
|
+
- yours are `request` (what only a person can give: a file, an asset, an access), `bug`, `finding` (a remark about the code or the project: a risk, debt, an analyzer's warning), `idea`, and `playtest` for the human's words in a playtest session
|
|
16
|
+
- a remark about the code is a `finding`, never a failure, which only a CI job files
|
|
12
17
|
- a text of several lines (its first line becomes the title) goes through stdin: `ai-factory gcf inbox add --text-file - <<'EOF'`, the lines, then `EOF`
|
|
13
18
|
- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
|
|
14
19
|
- 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
|
|
15
20
|
- `ai-factory gcf plan check <id>` lists the plan's form problems as `format:` lines: fix them, they never block
|
|
16
21
|
- drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
|
|
17
|
-
- a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings)
|
|
18
|
-
- a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote)
|
|
22
|
+
- answer a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) with `ai-factory gcf-harness metrics`
|
|
23
|
+
- answer a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote) with `ai-factory gcf-harness runs [--item <id>] --json`
|
|
24
|
+
- `ai-factory gcf-harness run <ids...> --model <m> --effort <e>` runs items on another model for that run only, the item unchanged
|
|
19
25
|
- after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green, at most `dod_attempts` of `gcf/config.yml` red runs; still red: block the item with the diagnosis
|
|
20
|
-
- the `live:` delta is YAML in the item's frontmatter, one of two forms
|
|
26
|
+
- the `live:` delta is YAML in the item's frontmatter, in one of two forms
|
|
27
|
+
- the first form: `live: {none: "<why it changes no capability>"}`
|
|
28
|
+
- the second form: `live:` with `changes:`, a list of `{id: <capability slug>, change: added | modified | removed, summary: "<at most two sentences>"}` (a removed one needs no summary)
|
|
21
29
|
- before `submit` or `close`, tick every task of the item's plan that is done, the verify and the review included: both refuse a plan with unticked tasks; `--unticked "<why>"` is the human's call, never the agent's
|
|
22
30
|
- `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
|
|
23
31
|
- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
|
|
24
32
|
- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
|
|
25
33
|
- 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
|
|
26
34
|
- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
|
|
27
|
-
- name each thing by the term `GLOSSARY.md` defines for it
|
|
35
|
+
- name each thing by the term `GLOSSARY.md` defines for it
|
|
36
|
+
- 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
|
|
37
|
+
- `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
|
|
28
38
|
- an `avoid:` lists only a word wrong in every document: a word with another use stays out, a phrase ("tile hand") beats a bare word
|
|
29
39
|
- the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --category playtest "<note>"`, in the human's words
|
|
30
40
|
- a release item carries `version:` and `channel:` (`item new --title "<title>" --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
|
|
31
41
|
- `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
|
|
32
42
|
- an item's milestone (`item new --milestone <name>`) is a `name` of the `milestones` in `gcf/game.md`, as a unit's: `item new` refuses another; a new milestone is a change of the vision, for the human (the gcf-vision skill)
|
|
33
|
-
- a milestone is a slice of the game the human plays as one, in `gcf/game.md`'s order
|
|
34
|
-
-
|
|
43
|
+
- a milestone is a slice of the game the human plays as one, in `gcf/game.md`'s order
|
|
44
|
+
- a mechanic or resource with a milestone gets `gate: auto` and closes unplayed, and the human plays it with the milestone
|
|
45
|
+
- a feature and a taken soft unit need a milestone while `gcf/game.md` lists milestones (`take --milestone <name>`)
|
|
46
|
+
- the lines of `platforms` in `gcf/game.md` are where the human can play the game; an item may narrow them in `play_on:`; they are a hint for the human, never a condition of a move
|
|
35
47
|
- the stops that wait for the human are the `gates:` of `gcf/config.yml` (`milestone`, `verdict`, `decision`, `question`) and each card's `skip_gates:`, both the human's (`config set`, `item gates`); the core applies them itself
|
|
36
48
|
- the board's autopilot starts the runs and the card sessions (`ai-factory gcf-harness card`) by itself and stops when a milestone is built for the human to play; an agent starts neither
|
|
37
|
-
- an item the human wants run on a given model or effort gets `item new --title "<title>" --model <m> --effort <e>`: the harness run passes both to the agent
|
|
49
|
+
- an item the human wants run on a given model or effort gets `item new --title "<title>" --model <m> --effort <e>`: the harness run passes both to the agent
|
|
50
|
+
- an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off), never a hand edit; its next run takes them
|
|
51
|
+
- an item without its own runs on the project's `agent.model` and `agent.effort` of `gcf/config.yml`, a setting of the human, and without those on opus, effort high
|
|
38
52
|
- where an item's runs go, the project folder or a worktree, is the human's choice: `ai-factory gcf item mode <id> --run main|worktree|default` over the project's `run_mode`, never a hand edit; set it only when the human asks
|
|
39
|
-
- before starting a run, `ai-factory gcf-harness gate --each <ids...> --json` says what the run gate refuses each item alone for now (it exits 0;
|
|
40
|
-
-
|
|
53
|
+
- before starting a run, `ai-factory gcf-harness gate --each <ids...> --json` says what the run gate refuses each item alone for now (it exits 0); `gate <ids...>` still gates a batch as a whole (exit 1)
|
|
54
|
+
- a session stops after `session_timeout_min` of `gcf/config.yml`, its item stays ready
|
|
55
|
+
- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`
|
|
56
|
+
- put an id in `depends` only when the item uses that one's data or code: `ai-factory gcf depends <id> --add <ids>` or `--remove <ids>`, never a hand edit
|
|
41
57
|
- what happened to an item before (who submitted, blocked, tuned or reranked it, and when) is `ai-factory gcf item history <id>`: its moves from git, an ended item's too
|
|
42
58
|
- a picture or file the human gives an item goes to `ai-factory gcf item attach <id> --file <path>` (its `gcf/work/<id>/attachments/`, committed); read an item's attachments before you plan it
|
|
43
|
-
- write what the human reads (a question, an assumption, a block reason, an inbox entry, a lesson, a report, an item's `title:`) in `language.ui` of `.ai-factory/config.yaml
|
|
44
|
-
- write
|
|
45
|
-
-
|
|
59
|
+
- write what the human reads (a question, an assumption, a block reason, an inbox entry, a lesson, a report, an item's `title:`) in `language.ui` of `.ai-factory/config.yaml`
|
|
60
|
+
- write the body of an item that is not a design unit in `language.artifacts` of `.ai-factory/config.yaml`
|
|
61
|
+
- write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `GLOSSARY.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary
|
|
62
|
+
- an answer that moves into a unit's slot goes there in English
|
|
63
|
+
- 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:`, `plan did not converge:`, `waits for`)
|
|
46
64
|
- 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`
|
|
47
|
-
- 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
|
|
65
|
+
- 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
|
|
66
|
+
- a new name saved with `design save` renames the id in every file that cites it
|
|
67
|
+
- `ai-factory gcf pillar retire <id> --reason "<why>"` takes a pillar out
|
|
48
68
|
- a design session (a vision interview, an import, the pillars interview, a debate's fixes) ends with `ai-factory gcf design commit -m "<what>"`: one commit of the design files, refused while the design check has a blocking finding
|
|
49
69
|
- a draft the human asked for (the glossary, a subsystem's purpose, the pillars' names) is written and not recorded: the human records it, edits it in its form or discards it (`ai-factory gcf design discard`)
|
|
50
|
-
- one part of the design (`pillars`, `game`, `glossary`, a subsystem, a unit) reads as fields with `ai-factory gcf design part <kind> <name> --json
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
- a
|
|
70
|
+
- one part of the design (`pillars`, `game`, `glossary`, a subsystem, a unit) reads as fields with `ai-factory gcf design part <kind> <name> --json`
|
|
71
|
+
- `ai-factory gcf design save <name> --kind <kind> --base <hash> --fields-file -` writes it back, refused when the part changed since its read
|
|
72
|
+
- a new unit is `design save --kind unit --system <s> --type <t> --title "<title>" --fields-file -`, its id printed first
|
|
73
|
+
- a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know; a note <= 4000 characters
|
|
74
|
+
- 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
|
|
75
|
+
- 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
|
|
76
|
+
- its `--text` replaces the blocks it names, `--add` adds to `notes:`; `--title` and `--from <in-id>` go with them
|
|
77
|
+
- 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
|
|
78
|
+
- 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
|
|
79
|
+
- so are the inbox's add, category, Later and erase
|
|
80
|
+
- the human's click makes each of those proposals
|
|
81
|
+
- in the project chat propose a new item by its title, never an id
|
|
82
|
+
- 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
|
|
54
83
|
- 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
|
|
55
|
-
-
|
|
56
|
-
-
|
|
84
|
+
- `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"}`
|
|
85
|
+
- 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
|
|
86
|
+
- `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
|
|
87
|
+
- `no_diff` in `gcf/config.yml` is the project's list of files shown without a diff
|
|
57
88
|
- a chat thread bound to an item reads the item's file, its plan, its run's log and run chat first (the paths its context names), answers the question, and only then proposes a move
|
|
58
89
|
|
|
59
90
|
gcf_forbidden:
|
|
60
91
|
- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md`, `gcf/inbox/` or `gcf/INDEX.md` by hand: the commands own them
|
|
61
92
|
- 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`
|
|
62
|
-
- the core refuses the human's moves to a harness run and a board chat
|
|
93
|
+
- 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
|
|
94
|
+
- those moves are `verdict`, `decide`, `drop` of a work item, `unblock`, `item amend`, `question answer`, `config set`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`
|
|
63
95
|
- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
|
|
64
96
|
- do not run `ai-factory gcf phase next`: the phase moves on the human's word only
|
|
65
97
|
- do not change what agent runs may do: `ai-factory gcf permissions`, its deny groups and the board's YOLO belong to the human
|