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/README.md +34 -7
- package/commands/gcf.js +218 -30
- package/extension.json +1 -1
- package/hooks/pre-commit.js +4 -2
- package/lib/agent-permissions.js +2 -2
- package/lib/audit-core.js +11 -5
- package/lib/board.js +41 -8
- package/lib/bundle.js +58 -13
- package/lib/config-set.js +2 -2
- package/lib/design-check.js +37 -9
- package/lib/design-parts.js +787 -0
- package/lib/design.js +2 -0
- package/lib/domain.js +406 -36
- package/lib/git.js +13 -6
- package/lib/history.js +1 -0
- package/lib/id.js +47 -0
- package/lib/inbox-categories.js +228 -0
- package/lib/inbox.js +238 -86
- package/lib/integrate.js +14 -2
- package/lib/lessons.js +11 -3
- package/lib/main-lock.js +17 -0
- package/lib/migrate.js +3 -3
- package/lib/transitions.js +2 -0
- package/lib/unit-ops.js +6 -2
- package/lib/validate-item.js +3 -0
- package/lib/work-ops.js +81 -10
- package/package.json +1 -1
- package/profiles/game.md +2 -2
- package/profiles/pillars.md +3 -3
- package/schemas/item.schema.json +1 -0
- package/skills/gcf-adopt/SKILL.md +1 -1
- package/skills/gcf-card/SKILL.md +2 -2
- package/skills/gcf-chat/SKILL.md +8 -5
- package/skills/gcf-debate/SKILL.md +2 -2
- package/skills/gcf-ingest/SKILL.md +5 -3
- package/skills/gcf-init/SKILL.md +13 -9
- package/skills/gcf-triage/SKILL.md +7 -7
- package/skills/gcf-vision/SKILL.md +8 -3
- package/templates/PILLARS.md +2 -0
- package/templates/agents-block.md +14 -6
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
1357
|
+
locked(projectDir, !spec.dryRun, () => newItemUnlocked(projectDir, spec));
|
package/package.json
CHANGED
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
|
package/profiles/pillars.md
CHANGED
|
@@ -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
|
package/schemas/item.schema.json
CHANGED
|
@@ -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..
|
|
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`
|
package/skills/gcf-card/SKILL.md
CHANGED
|
@@ -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?";
|
|
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 <
|
|
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
|
package/skills/gcf-chat/SKILL.md
CHANGED
|
@@ -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
|
-
-
|
|
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
|
|
35
|
-
5. a raw thought that is not work yet: propose
|
|
36
|
-
6. a move the human asks for
|
|
37
|
-
7.
|
|
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
|
|
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.
|
|
63
|
-
22.
|
|
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
|
package/skills/gcf-init/SKILL.md
CHANGED
|
@@ -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
|
|
27
|
-
5.
|
|
28
|
-
6.
|
|
29
|
-
7.
|
|
30
|
-
8.
|
|
31
|
-
9.
|
|
32
|
-
10.
|
|
33
|
-
11. to
|
|
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`:
|
|
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
|
|
22
|
-
- do not triage on a `work/` branch: `inbox
|
|
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 (`
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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
|
package/templates/PILLARS.md
CHANGED
|
@@ -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
|
-
-
|
|
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 --
|
|
25
|
-
- a release item carries `version:` and `channel:` (`item new <
|
|
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
|
|
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
|
|
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
|