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.
@@ -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 edit or delete a file in `gcf/inbox/` by hand: `ai-factory gcf item new --from`, `ai-factory gcf inbox category`, `inbox later` and `inbox drop` own the entries
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 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>`
33
- 9. 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>`
34
- 10. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
35
- 11. 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
36
- 12. report what each entry became and how many entries remain
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; name an item or a unit to the human by its title with the id in brackets, "double jump (dvoinoi-pryzhok)"; 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, at most 4 words joined by hyphens, `-2` when taken
10
- - 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; a text that starts with a hyphen goes as `inbox add --text="<text>"`
11
- - an agent names the category: `ai-factory gcf inbox categories` lists them and who may file each; 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; a remark about the code is a `finding`, never a failure, which only a CI job files
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) is answered by `ai-factory gcf-harness metrics`
18
- - a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote) is answered by `ai-factory gcf-harness runs [--item <id>] --json`; `ai-factory gcf-harness run <ids...> --model <m> --effort <e>` runs items on another model for that run only, the item unchanged
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: `live: {none: "<why it changes no capability>"}`, or `live:` with `changes:`, a list of `{id: <capability slug>, change: added | modified | removed, summary: "<at most two sentences>"}` (a removed one needs no summary)
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; a word added to an `avoid:` there leaves `gcf/design/`, `gcf/systems/`, `gcf/PILLARS.md` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit in design and items as M4, `npx --yes cnlp-kit check` the rest
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; a mechanic or resource with one gets `gate: auto`, closes unplayed and is played with it; a feature and a taken soft unit need one while `gcf/game.md` lists them (`take --milestone <name>`)
34
- - the lines of `platforms` in `gcf/game.md` are where the game can be played; an item may narrow them in `play_on:`; they are a hint for the human, never a condition of a move
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; 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; 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
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; a batch is still gated as a whole by `gate <ids...>`, exit 1); a session stops after `session_timeout_min` of `gcf/config.yml`, its item stays ready
40
- - ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and 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
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`, and the body of an item that is not a design unit in its `language.artifacts`
44
- - 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; an answer that moves into a unit's slot goes there in English
45
- - never 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`)
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: a new name saved with `design save` renames the id wherever it is cited; `ai-factory gcf pillar retire <id> --reason "<why>"` takes one out
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`; `ai-factory gcf design save <name> --kind <kind> --base <hash> --fields-file -` writes it back, refused when the part changed since its read; a new unit is `design save --kind unit --system <s> --type <t> --title "<title>" --fields-file -`, its id printed first
51
- - a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know, up to 4000 characters
52
- - in the project chat (the gcf-chat skill) a new item is proposed with the `propose_item_new` tool of the `gcf` MCP server, not made with `item new`: the human's click makes it; so are a block, a drop, a dependency change, an unblock, a verdict, a decision, an answer to an open question and the inbox's add, category, Later and erase, with their `propose_` tools and the `id` they act on; a new item is proposed by its title, never an id
53
- - a verdict is proposed only after the human said in the talk that they played the item and how it felt, its note in the human's words; the `remove` of a kill, a no or a wontfix is left to the rule unless the human says otherwise
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
- - a move the commit gate refuses ends its error with `gcf-refusal: {"code":"gate","problems":[…]}`: nothing was committed; fix what it names, then make the move again
56
- - `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; `no_diff` in `gcf/config.yml` is the project's list of files shown without a diff
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 (`verdict`, `decide`, `drop` of a work item, `unblock`, `question answer`, `config set`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`): bring the move to the human, or block the item with the question
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