gcf-aif-ext 0.15.0 → 0.18.3

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/lib/work-ops.js CHANGED
@@ -10,11 +10,11 @@ import { createHash } from 'node:crypto';
10
10
  import path from 'node:path';
11
11
  import { parse, serialize } from './frontmatter.js';
12
12
  import { buildLedger } from './ledger.js';
13
- import { readConfig, RUN_WORD } from './gcf-paths.js';
13
+ import { readConfig, RUN_MODES, RUN_WORD } from './gcf-paths.js';
14
14
  import { atomicWrite, resolveInside } from './safe-path.js';
15
15
  import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
16
16
  import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
17
- import { isValidId } from './id.js';
17
+ import { deriveId, isValidId } from './id.js';
18
18
  import { commitMove, addConstraints, onWorkBranch } from './unit-ops.js';
19
19
  import { openSystemDoc, upsertBlock } from './systems-doc.js';
20
20
  import {
@@ -35,8 +35,8 @@ import {
35
35
  revertDelta,
36
36
  knownIssueOf,
37
37
  } from './live.js';
38
- import { planTake, untrackedEntries } from './inbox.js';
39
- import { cycleMessage, dependsGraph, pathTo } from './design-check.js';
38
+ import { inboxEntry, planTake, untrackedEntries } from './inbox.js';
39
+ import { cycleMessage, dependsGraph, gameMilestones, pathTo } from './design-check.js';
40
40
  import { refuseByPhase } from './phase.js';
41
41
  import { locked, runHolder } from './main-lock.js';
42
42
  import { dropAgentSession, ownsMark, releaseSession, sessionActive } from './session-mark.js';
@@ -843,7 +843,7 @@ function checkRelease(spec) {
843
843
 
844
844
  const RUN_KEYS = ['model', 'effort'];
845
845
 
846
- // The value that leaves a model or effort to the agent: no flag on its command line.
846
+ // The value that takes an item's model or effort off: the project's, else Opus and High, hold.
847
847
  const AGENT_DEFAULT = 'default';
848
848
 
849
849
  /** Refuse a model or effort that is not one plain word (`default` included). */
@@ -902,6 +902,8 @@ function checkDepends(ledger, id, depends, { added = depends, parent = null } =
902
902
  function checkNew(ledger, spec) {
903
903
  const { id, type, gate, severity } = spec;
904
904
  if (!isValidId(id)) throw new Error(`${id} is not a lowercase hyphen slug`);
905
+ if (spec.parent && !isValidId(spec.parent))
906
+ throw new Error(`--parent is one feature item, not ${spec.parent}`);
905
907
  if (ledger.known(id)) throw new Error(`${id} is taken already: ids are never reused`);
906
908
  if (!ITEM_TYPES.includes(type)) throw new Error(`type must be ${ITEM_TYPES.join(' | ')}`);
907
909
  if (UNIT_ITEM_TYPES.includes(type))
@@ -1070,7 +1072,7 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1070
1072
 
1071
1073
  /**
1072
1074
  * Set how item `id`'s runs go: its `model` and `effort`, each given one a plain word, `default`
1073
- * taking the field off (the project's `agent.model|effort`, else the agent's own choice). One commit `gcf(item)`. A run in progress keeps
1075
+ * taking the field off (the project's `agent.model|effort`, else Opus and High). One commit `gcf(item)`. A run in progress keeps
1074
1076
  * its own; the item's next run takes the new value.
1075
1077
  * @param {string} projectDir
1076
1078
  * @param {string} id
@@ -1107,6 +1109,42 @@ async function setAgentUnlocked(projectDir, id, { model, effort, commit = true }
1107
1109
  return { ...result, hash };
1108
1110
  }
1109
1111
 
1112
+ /**
1113
+ * Set where item `id`'s runs go (Methodology §7): `main` or `worktree` over the project's
1114
+ * `run_mode`, `default` taking the field off. One commit `gcf(item)`; the next run takes it.
1115
+ * Which one a project's work needs is the operator's to know: the framework does not judge it.
1116
+ * @param {string} projectDir
1117
+ * @param {string} id
1118
+ * @param {{run?: string, commit?: boolean}} [opts]
1119
+ */
1120
+ async function setRunModeUnlocked(projectDir, id, { run, commit = true } = {}) {
1121
+ if (run !== AGENT_DEFAULT && !RUN_MODES.includes(run ?? ''))
1122
+ throw new Error(`--run is ${[...RUN_MODES, AGENT_DEFAULT].join(' | ')}`);
1123
+ const ledger = await buildLedger(projectDir);
1124
+ const item = ledger.item(id);
1125
+ if (!item) throw new Error(`${id} is not a work item`);
1126
+ refuseRunning(projectDir, id);
1127
+ const data = { ...item.data };
1128
+ if (run === AGENT_DEFAULT) delete data.run_mode;
1129
+ else data.run_mode = run;
1130
+ const result = { id, run_mode: data.run_mode ?? null };
1131
+ if (data.run_mode === item.data.run_mode) return { ...result, hash: null };
1132
+ const hash = await commitMove(
1133
+ projectDir,
1134
+ `gcf(item): ${id} runs in ${data.run_mode ?? AGENT_DEFAULT}`,
1135
+ {
1136
+ files: [item.file],
1137
+ inputs: [item.file],
1138
+ mutate: () => atomicWrite(item.file, serialize(data, item.body)),
1139
+ commit,
1140
+ key: 'mode',
1141
+ items: [id],
1142
+ },
1143
+ );
1144
+
1145
+ return { ...result, hash };
1146
+ }
1147
+
1110
1148
  // An attachment is a picture or a file the operator gave the item (a chat image, a reference).
1111
1149
  const ATTACH_MAX = 10 * 1024 * 1024;
1112
1150
 
@@ -1170,10 +1208,35 @@ function parentWrite(ledger, spec) {
1170
1208
  return [[p.file, serialize({ ...p.data, children }, p.body)]];
1171
1209
  }
1172
1210
 
1173
- async function newItemUnlocked(projectDir, spec) {
1211
+ /**
1212
+ * The title an item without an id gets its id from (Board-PRD decision 34): the one given, else
1213
+ * its inbox entry's.
1214
+ */
1215
+ async function titleForId(root, spec) {
1216
+ const title = spec.title?.trim() || (spec.from ? (await inboxEntry(root, spec.from)).title : '');
1217
+ if (!title)
1218
+ throw new Error('a new item needs --title (or --from an inbox entry): its id comes from it');
1219
+
1220
+ return title;
1221
+ }
1222
+
1223
+ async function newItemUnlocked(projectDir, given) {
1174
1224
  const root = gcfOf(projectDir);
1175
1225
  const ledger = await buildLedger(projectDir);
1226
+ // The system's id, made under the lock that writes it: two moves never take one id.
1227
+ const spec = given.id
1228
+ ? given
1229
+ : { ...given, id: deriveId(await titleForId(root, given), ledger.known, given.type) };
1176
1230
  const gate = checkNew(ledger, spec);
1231
+ const milestones = spec.milestone ? await gameMilestones(root) : null;
1232
+ if (milestones && !milestones.some((m) => m.name === spec.milestone))
1233
+ throw new Error(
1234
+ `--milestone ${spec.milestone} is not a milestone of game.md: ` +
1235
+ (milestones.map((m) => m.name).join(', ') || 'it lists none'),
1236
+ );
1237
+ if (spec.proposal !== undefined && !/^[\w-]+\/[\w-]+$/.test(spec.proposal))
1238
+ throw new Error(`--proposal is <thread>/<proposal id>, not ${spec.proposal}`);
1239
+ if (spec.dryRun) return { id: spec.id, item: `gcf/work/${spec.id}.md`, hash: null };
1177
1240
  await refuseByPhase(projectDir, spec.type, spec.reopens);
1178
1241
  if (spec.reopens && !ledger.where(spec.reopens).terminal.length)
1179
1242
  throw new Error(`reopens names ${spec.reopens}, which has not ended`);
@@ -1202,9 +1265,10 @@ async function newItemUnlocked(projectDir, spec) {
1202
1265
  commit: spec.commit ?? false,
1203
1266
  key: 'item-new',
1204
1267
  items: [spec.id, ...(spec.parent ? [spec.parent] : [])],
1268
+ proposal: spec.proposal,
1205
1269
  });
1206
1270
 
1207
- return { item: `gcf/work/${spec.id}.md`, hash };
1271
+ return { id: spec.id, item: `gcf/work/${spec.id}.md`, hash };
1208
1272
  }
1209
1273
 
1210
1274
  /**
@@ -1281,6 +1345,13 @@ export const setDepends = (projectDir, id, opts = {}) =>
1281
1345
  /** @type {typeof setAgentUnlocked} */
1282
1346
  export const setAgent = (projectDir, id, opts = {}) =>
1283
1347
  locked(projectDir, opts.commit ?? true, () => setAgentUnlocked(projectDir, id, opts));
1284
- /** @type {typeof newItemUnlocked} */
1348
+ /** @type {typeof setRunModeUnlocked} */
1349
+ export const setRunMode = (projectDir, id, opts = {}) =>
1350
+ locked(projectDir, opts.commit ?? true, () => setRunModeUnlocked(projectDir, id, opts));
1351
+ /**
1352
+ * Locked with a commit or without: the id it may make comes from the ledger it reads, and a move
1353
+ * meanwhile could take the same one.
1354
+ * @type {typeof newItemUnlocked}
1355
+ */
1285
1356
  export const newItem = (projectDir, spec) =>
1286
- locked(projectDir, spec.commit ?? false, () => newItemUnlocked(projectDir, spec));
1357
+ locked(projectDir, !spec.dryRun, () => newItemUnlocked(projectDir, spec));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.15.0",
3
+ "version": "0.18.3",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/profiles/game.md CHANGED
@@ -52,7 +52,7 @@ sections:
52
52
  required: yes
53
53
  record_keys: name, goal
54
54
  optional_record_keys: content
55
- note: the closed vocabulary of a unit's milestone field; content is a volume written as a comparison
55
+ note: the closed vocabulary of a unit's and a work item's milestone field; content is a volume written as a comparison
56
56
 
57
57
  - key: provenance
58
58
  form: record-list
@@ -65,4 +65,4 @@ custom_sections:
65
65
  - none: a block that is not listed above belongs to a unit or to PILLARS.md
66
66
 
67
67
  enforcement:
68
- - `ai-factory gcf design check` resolves every unit's milestone against this file
68
+ - `ai-factory gcf design check` resolves every unit's and work item's milestone against this file
@@ -21,11 +21,11 @@ sections:
21
21
  form: record-list
22
22
  required: yes
23
23
  record_keys: statement, invariant, review_question
24
- optional_record_keys: id
25
- note: pillar count <= 7 and the token budget are enforced by the gcf audit core; id is the slug a design unit cites in pillars:
24
+ optional_record_keys: id, name
25
+ note: pillar count <= 7 and the token budget are enforced by the gcf audit core; name is the few words the operator knows it by; id is the slug a design unit cites in pillars:, made from the name and never typed
26
26
 
27
27
  custom_sections:
28
- - none: a pillar that needs more than its statement, invariant, review question and id is not a pillar yet
28
+ - none: a pillar that needs more than its name, statement, invariant, review question and id is not a pillar yet
29
29
 
30
30
  enforcement:
31
31
  - `npx --yes cnlp-kit check`, over the file a `cnlp.config.json` corpus entry maps to this profile
@@ -100,6 +100,7 @@
100
100
  },
101
101
  "model": { "$ref": "#/definitions/textOrNull" },
102
102
  "effort": { "$ref": "#/definitions/textOrNull" },
103
+ "run_mode": { "enum": ["main", "worktree", null] },
103
104
  "version": {
104
105
  "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^\\S+$" }]
105
106
  },
@@ -32,7 +32,7 @@ workflow:
32
32
  6. fill `purpose:` with one line of intent the human confirmed: the INDEX row of a subsystem is its first `purpose` bullet
33
33
  7. fill `behavior:` and `constraints:` with 1 placeholder each, annotated `[until: manual(first verdict touching <name>)]`: the profile requires both blocks, and a `manual(...)` trigger is not an audit finding
34
34
  8. write a constraint the human states out loud into `constraints:`, and do not interview subsystem by subsystem for more: unanswered questions on adoption day are the staleness this framework exists to remove
35
- 9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..6, and do not restate that interview here
35
+ 9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..8, and do not restate that interview here
36
36
  10. run `npx --yes cnlp-kit check` (it covers the systems docs and PILLARS of `cnlp.config.json`, not design units), then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
37
37
  11. ask the human to run `ai-factory gcf hooks-install`; when it refuses over a foreign pre-commit, hand them the chain line it prints
38
38
  12. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
@@ -33,10 +33,10 @@ outputs:
33
33
  - every item carries a `live:` delta before it ends: what it adds, modifies or removes in `gcf/LIVE.md`, or `none: <why>`
34
34
 
35
35
  workflow:
36
- 1. for a free-text design idea: ask "into work now, or park it?"; write a unit in the matching `gcf/design/<system>.md` with `source: manual` and `TBD` slots, append `- <id>` to `gcf/backlog.md`, and on "park" stop here
36
+ 1. for a free-text design idea: ask "into work now, or park it?"; `ai-factory gcf design save --kind unit --system <s> --type <t> --title "<title>" --fields-file -`, `{}` on stdin, writes it with `TBD` slots and prints its id; on "park" stop here
37
37
  2. for non-design work: pick the type - tech, bug, spike, asset, content, perf, release - among those `ai-factory gcf phase` says the phase takes, and propose the gate its type gives; the human may flip it (`--gate auto` is "no playtest")
38
38
  3. a bug needs `--severity <level>` and a `repro:` the human confirms; a release needs `--release <version> --channel <name>` from the human; those flags go on the `item new` of step 4
39
- 4. run `ai-factory gcf item new <id> --type <type> [--gate <gate>] [--parent <feature>] [--title "<line>"]`, `--from <in-id>` from the inbox, `--blocked "file needed"` for an asset; write `intent:`, a bug's `repro:` and `live:`; stop
39
+ 4. run `ai-factory gcf item new --title "<line>" --type <type> [--gate <gate>] [--parent <feature>]`, `--from <in-id>` from the inbox, `--blocked "file needed"` for an asset; it prints the id first; write `intent:`, a bug's `repro:` and `live:`; stop
40
40
  5. for a design unit: run `ai-factory gcf where <id>`; the id must be a single unit of `gcf/design/`; read its section from the file the command names
41
41
  6. for a unit with `flags: impl?` ask the human first whether the mechanic already ships; on "yes" run `ai-factory gcf drop <id> --reason "already ships"` and stop
42
42
  7. for a unit with `flags: src-changed` re-read each changed anchor with `ai-factory gcf section`, rebuild the slots whose quote moved, and remove the flag
@@ -8,7 +8,8 @@ mode: human gate
8
8
  purpose:
9
9
  - answer the human's questions about the game, its design, its work items and its runs from what `gcf/` and the run files say
10
10
  - turn a bug, an idea or a task the talk finds into a proposed work item the human accepts with one click
11
- - make a move the human asks for through its `ai-factory gcf` command, which the chat shows the human as a card first
11
+ - propose a move on an item or an inbox entry (block, drop, depends, inbox add, category, Later, erase) as a card the human makes with one click
12
+ - make another move the human asks for through its `ai-factory gcf` command, which the chat shows the human as a card first
12
13
 
13
14
  inputs:
14
15
  - the human's messages, one turn each
@@ -22,6 +23,7 @@ forbidden_behaviors:
22
23
  - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`; the rules refuse them to any agent
23
24
  - do not run `ai-factory gcf-harness run|stop|chat|init` or `ai-factory extension`: the rules refuse them; name the board's button instead
24
25
  - do not make a new item with `ai-factory gcf item new`: propose it with the `propose_item_new` tool of the `gcf` MCP server, and the human's click makes it
26
+ - do not run the command of a move that has a `propose_` tool of the `gcf` MCP server (`propose_block`, `propose_drop`, `propose_depends`, `propose_inbox_add`, `propose_inbox_category`, `propose_inbox_later`, `propose_inbox_drop`): call the tool
25
27
  - do not write code or edit files to fix what the talk finds: a fix is a work item, and its run builds it
26
28
  - do not answer from memory what a file says: read the file, then answer
27
29
  - do not ask again for a move the human refused: say what it would have done and leave it
@@ -31,10 +33,11 @@ workflow:
31
33
  1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
32
34
  2. a thread bound to an item: read the item's file, its plan, its run's log and run chat first, the paths the context file names, before the first answer
33
35
  3. answer the question from the files you read, with the paths that say it; for the runs' numbers run `ai-factory gcf-harness metrics` when the project has the harness
34
- 4. a bug, an idea or a task that is new work: call `propose_item_new` with its id, type, title, subsystems and a note of what its run should know; note length <= 4000 characters
35
- 5. a raw thought that is not work yet: propose to put it in the inbox with `ai-factory gcf inbox add`
36
- 6. a move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
37
- 7. say in one line what changed, or that nothing did
36
+ 4. a bug, an idea or a task that is new work: call `propose_item_new` with its title, type, subsystems and a note of what its run should know, no id: the core makes it from the title; note length <= 4000 characters
37
+ 5. a raw thought that is not work yet: propose it for the inbox with `propose_inbox_add` and the category it is: `idea`, `request` (what only a person can give), `bug` or `finding` (a remark about the code), a detail word when one fits
38
+ 6. a move the human asks for, or one the talk shows is due, that has a `propose_<move>` tool: call it with the `id` of the item or inbox entry it acts on, and say why in one line; name an item by its title with the id in brackets
39
+ 7. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
40
+ 8. say in one line what changed, or that nothing did
38
41
 
39
42
  invocation:
40
43
  - run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
@@ -29,8 +29,8 @@ workflow:
29
29
  4. cross-examine: for each pair of findings that touch one unit or anchor, check whether they contradict each other and merge or escalate
30
30
  5. classify each finding: D2 gets a proposed default the human can skim; D1 is a principal fork and carries the question, the units in `blocks:` and a proposed answer
31
31
  6. report by lens, ordered by damage: contradictions first, then holes, then dictionary drift; cite unit ids or anchors, quote lines <= 15 words
32
- 7. append D1 and D2 records to `gcf/open-questions.md` when `gcf/` exists; otherwise put them into the report only
33
- 8. offer the fixes: apply each agreed edit to its unit in place, with `answer: manual` in its provenance, one go-ahead per edit, then run `ai-factory gcf design check`
32
+ 7. append D1 and D2 records to `gcf/open-questions.md` when `gcf/` exists, and record them with `ai-factory gcf design commit -m "debate findings"`; otherwise put them into the report only
33
+ 8. offer the fixes: apply each agreed edit to its unit in place, with `answer: manual` in its provenance, one go-ahead per edit, then run `ai-factory gcf design check` and `ai-factory gcf design commit -m "debate fixes"`
34
34
 
35
35
  invocation:
36
36
  - run on a fresh GDD before ingest, on the Design Model after an import or a big revision, or on demand
@@ -10,7 +10,7 @@ purpose:
10
10
  - write into a slot only what the GDD says: a verbatim quote backs the value, and every other slot reads `TBD`
11
11
 
12
12
  inputs:
13
- - a path to the GDD (markdown)
13
+ - a path to the GDD (markdown); a file the board uploaded lives under `.gcf-session/`, and `ai-factory gcf anchor` copies it into `gcf/source/` under its own name
14
14
 
15
15
  preconditions:
16
16
  - `gcf/` exists (run gcf-init first)
@@ -59,8 +59,10 @@ workflow:
59
59
  18. on a re-import, raise a D1 for a work item or a collapsed system that cites a changed anchor, and run steps 3..16 over the text no quote covers any more
60
60
  19. mark a unit whose nouns match the `purpose` or the `code` paths of an existing systems doc with `flags: impl?`: the mechanic may already ship, and the human drops it with `ai-factory gcf drop`
61
61
  20. append the new ids to `gcf/backlog.md`, run `ai-factory gcf design check`, fix every blocking finding, then run `ai-factory gcf anchor <file> --done`: until then a rerun gets the same delta
62
- 21. report the package, ordered: D1 questions (the main product), pillar candidates, glossary conflicts, the design summary per subsystem, D2 assumptions; say when `impl?` was blind
63
- 22. state the next step: answer the D1s, confirm pillars and glossary, then take the first unit with `/gcf-card <id>`
62
+ 21. record the import with `ai-factory gcf design commit -m "import <file>"`
63
+ 22. report the package, ordered: D1 questions (the main product), pillar candidates, glossary conflicts, the design summary per subsystem, D2 assumptions; say when `impl?` was blind
64
+ 23. write `gcf/game.md` and `gcf/glossary.md` as the human confirms them, and record them with `ai-factory gcf design commit`
65
+ 24. state the next step: answer the D1s, confirm pillars and glossary, then take the first unit with `/gcf-card <id>`
64
66
 
65
67
  invocation:
66
68
  - run when a GDD arrives or changes
@@ -21,16 +21,20 @@ forbidden_behaviors:
21
21
 
22
22
  workflow:
23
23
  1. when `.ai-factory/DESCRIPTION.md` is absent, tell the human to run `/aif` first: `aif-plan` reads it, and a work item cannot reach a plan without it
24
- 2. run `ai-factory gcf init` and report which files it created, `gcf/design/` and the agent instructions in `AGENTS.md` among them; it writes no `PILLARS.md`
24
+ 2. when `gcf/` is absent, run `ai-factory gcf init` and report which files it created, `gcf/design/` and the agent instructions in `AGENTS.md` among them; it writes no `PILLARS.md`
25
25
  3. when the human is about to import a GDD, leave `PILLARS.md` absent: the import proposes pillar candidates, and the interview runs after it
26
- 4. otherwise ask the human for the game's core promise, then for 2..7 pillars: each needs an id (a lowercase hyphen slug the design units cite), a statement, a negative invariant and a review question
27
- 5. write `gcf/PILLARS.md` with the confirmed pillars, word for word, in the record-list form of `.ai-factory/extensions/gcf-aif-ext/templates/PILLARS.md`: the human decides each pillar, you only write it down
28
- 6. run `npx --yes cnlp-kit check` and fix form issues it reports; it checks only the systems docs and PILLARS of `cnlp.config.json`: units go through `ai-factory gcf design check`, the tree through `ai-factory gcf audit`
29
- 7. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
30
- 8. state the next step: import a GDD with `/gcf-ingest`, or start the design with `/gcf-vision` when there is none
31
- 9. to add one pillar later, ask only for its id, statement, invariant and review question; append it as one record to `gcf/PILLARS.md`, keep the others, keep the count <= 7, then run step 6
32
- 10. to rename a pillar, run `ai-factory gcf pillar rename <from> <to>`: every unit and item citing it follows
33
- 11. to drop a pillar, run `ai-factory gcf pillar retire <id> --reason "<why>"`; a unit it leaves at `pillars: TBD` goes back through the pillars steps of the gcf-card skill
26
+ 4. otherwise start from the pillar candidates an import left in `gcf/open-questions.md`; with none and `gcf/PILLARS.md` empty, draw candidates from `gcf/game.md` and the units of `gcf/design/`
27
+ 5. ask the human for the game's core promise, then for 2..7 pillars: each a name of 2..4 words, a statement, a negative invariant and a review question; its id, which units cite, is the name in Latin lowercase joined by hyphens
28
+ 6. write `gcf/PILLARS.md` with the confirmed pillars, word for word, in the record-list form of `.ai-factory/extensions/gcf-aif-ext/templates/PILLARS.md`: the human decides each pillar, you only write it down
29
+ 7. run `npx --yes cnlp-kit check` and fix form issues it reports; it checks only the systems docs and PILLARS of `cnlp.config.json`: units go through `ai-factory gcf design check`, the tree through `ai-factory gcf audit`
30
+ 8. record the pillars with `ai-factory gcf design commit -m "pillars"`
31
+ 9. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
32
+ 10. state the next step: import a GDD with `/gcf-ingest`, or start the design with `/gcf-vision` when there is none
33
+ 11. to add one pillar later, ask only for its name, statement, invariant and review question; append it as one record to `gcf/PILLARS.md` with the id from its name, keep the others, keep the count <= 7, then run steps 7..8
34
+ 12. a pillar's new name is saved from the board's form or with `ai-factory gcf design save pillars --kind doc`: its id follows the name, in every unit and item citing it; `ai-factory gcf pillar rename <from> <to>` stays for the console
35
+ 13. to name the pillars that have none (the board's Name with agent): write a `name:` of 2..4 words from each one's statement into its record, change nothing else, and do not record it: the human records, edits or discards the draft
36
+ 14. a run and a board chat have no pillar moves: there the human renames or retires a pillar, on the board's Design screen
37
+ 15. to drop a pillar, run `ai-factory gcf pillar retire <id> --reason "<why>"`; a unit it leaves at `pillars: TBD` goes back through the pillars steps of the gcf-card skill
34
38
 
35
39
  invocation:
36
40
  - run when the user asks to set up gcf in a project, or to revise its pillars
@@ -9,7 +9,7 @@ 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
10
 
11
11
  inputs:
12
- - `gcf/inbox/in-<id>.md`, one file an entry, read through `ai-factory gcf inbox --json`: each entry has a `title` (its first line) and a `text` that may run several lines
12
+ - `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
13
13
 
14
14
  preconditions:
15
15
  - `gcf/` exists and the inbox holds entries
@@ -18,21 +18,21 @@ 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 tag` and `ai-factory gcf inbox drop` own the entries
22
- - do not triage on a `work/` branch: `inbox tag`, `inbox drop` and `item new --from` refuse there; triage on main
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
22
+ - do not triage on a `work/` branch: `inbox category`, `inbox later`, `inbox drop` and `item new --from` refuse there; triage on main
23
23
 
24
24
  workflow:
25
25
  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
27
- 3. a lesson (`source: lesson`, with its `kind` and 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
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
+ 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
28
  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
29
  5. present the calls to the human, calls per message <= 5, and apply only the approved ones
30
- 6. a bug or other work: run `ai-factory gcf item new <id> --type <type> [--severity <level>] --from <in-id>`, then write its `intent:` and `repro:`
30
+ 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
31
  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
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
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
34
  10. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
35
- 11. an entry the human keeps for later (an idea, a note): tag it with the tag the human names, `ai-factory gcf inbox tag <in-id> --add <tags>`, and leave it in the inbox
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
36
  12. report what each entry became and how many entries remain
37
37
 
38
38
  invocation:
@@ -12,7 +12,8 @@ inputs:
12
12
  - none: the skill discovers everything by asking the human
13
13
 
14
14
  preconditions:
15
- - no GDD exists yet; when one exists, route to gcf-debate or gcf-ingest instead
15
+ - a new interview needs a project with no GDD: `gcf/source/` holds no file; when one exists, route to gcf-debate or gcf-ingest instead
16
+ - a change of an existing `gcf/game.md` goes by the revise steps 9..10, not by a new interview
16
17
  - `gcf/` exists: run `ai-factory gcf init` first when it does not
17
18
 
18
19
  forbidden_behaviors:
@@ -32,8 +33,12 @@ workflow:
32
33
  4. ask what the game is NOT: negative answers seed the pillars and the scope_out list, and cost the least
33
34
  5. write `gcf/game.md` from the answers, and read it back to the human for corrections
34
35
  6. name the subsystems and the units with the human: each player verb a mechanic, each currency a resource, each invariant a rule; write each unit with the header of `templates/design.md` and the blocks `profiles/unit-<type>.md` lists for its type
35
- 7. write `gcf/backlog.md` in the human's ranking, then run `ai-factory gcf design check` and fix every blocking finding
36
+ 7. write `gcf/backlog.md` in the human's ranking, run `ai-factory gcf design check`, fix every blocking finding, then run `ai-factory gcf design commit -m "vision interview"`: it records the design files in one commit
36
37
  8. state the next step: `/gcf-init` for the pillars interview, `/gcf-debate` to stress the design, then `/gcf-card <id>` for the first unit
38
+ 9. to change the vision, scope or milestones later, read `gcf/game.md`, ask what changes, write only the blocks that change, and read them back to the human
39
+ 10. a milestone renamed while units cite it fails the design check: change the `milestone:` of each citing unit too, then run `ai-factory gcf design check` and `ai-factory gcf design commit -m "<what changed>"`
40
+ 11. a draft of the glossary (the board's Draft with agent): from `gcf/game.md` and the units, write `gcf/glossary.md` in the form of `templates/glossary.md`; do not record it: the human records, edits or discards it
41
+ 12. a draft of a subsystem's purpose: read its units in `gcf/design/<system>.md` and `gcf/game.md`, write its `purpose:` block, change nothing else, and do not record it
37
42
 
38
43
  invocation:
39
- - run at project start, before any design exists
44
+ - run at project start, before any design exists, to change the vision later, or for a draft of the glossary or a subsystem's purpose
@@ -1,10 +1,12 @@
1
1
  pillars:
2
2
  - statement: every encounter is readable at a glance
3
+ name: Readable encounters
3
4
  invariant: no effect ever hides the player character
4
5
  review_question: does this change add visual noise over the player
5
6
  id: readable-encounters
6
7
 
7
8
  - statement: death is the player's fault, never the camera's
9
+ name: Fair camera
8
10
  invariant: no off-screen damage sources
9
11
  review_question: can this change hurt the player from outside the view
10
12
  id: fair-camera
@@ -6,7 +6,9 @@ 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
- - a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>" [--tags <a,b>]` (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>"`
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
10
12
  - 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`
11
13
  - before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
12
14
  - 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
@@ -21,10 +23,12 @@ gcf_work:
21
23
  - 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
22
24
  - a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
23
25
  - a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
24
- - the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
25
- - a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
26
+ - 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
27
+ - 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`
26
28
  - `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
27
- - an item the human wants run on a given model or effort gets `item new <id> --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
29
+ - 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)
30
+ - 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
31
+ - 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
28
32
  - 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
29
33
  - 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
30
34
  - 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
@@ -33,9 +37,12 @@ gcf_work:
33
37
  - write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `gcf/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
34
38
  - 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`)
35
39
  - 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`
36
- - a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
40
+ - 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
41
+ - 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
42
+ - 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`)
43
+ - 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
37
44
  - a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know, up to 4000 characters
38
- - 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
45
+ - 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 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
39
46
  - 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
40
47
 
41
48
  gcf_forbidden:
@@ -54,3 +61,4 @@ gcf_skills:
54
61
  - gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
55
62
  - gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
56
63
  - gcf-chat is the board's project chat: answers from `gcf/` and the runs, proposals of new items, the moves the human approves
64
+ - a thread the board's Design screen opens follows the skill it names (gcf-vision, gcf-ingest, gcf-debate, gcf-init or gcf-card), not gcf-chat: its first message says what to do