gcf-aif-ext 0.2.0

package/skills/gcf-card/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gcf-card
+description: Materialize a GCF card from a backlog candidate or a fresh idea - slots, hard/soft routing, depends. Use when work starts on a feature or the user says "заведи карточку".
+---
+
+mode: authoring
+
+purpose:
+- turn a backlog candidate or a fresh idea into a card file with the six slots filled
+
+inputs:
+- a cand-NNN id from `gcf/backlog.md`, or a free-text feature idea
+
+preconditions:
+- `gcf/` exists; `gcf/INDEX.md` lists the current subsystems
+
+forbidden_behaviors:
+- do not invent a new subsystem name when INDEX carries a synonym: reuse or ask (GCF-PRD §5.4)
+- do not write numbers outside the feel slot envelopes
+- do not put `until:` in the frontmatter: it is a line annotation inside slots
+- do not fill a slot with a guess: an unknown goes to `gcf/open-questions.md`, marked D1 or D2
+
+workflow:
+1. read `gcf/INDEX.md`; for a cand-NNN input read its backlog line, otherwise ask "into work now, or park in the backlog?" and on "park" append a candidate line and stop
+2. route the requirement: ask "can an autotest accept this without a human playing?"; yes = hard, no or mixed = soft; state the route in one line and let the human veto
+3. for a pure hard route: send the requirement to the normal AIF cycle, add any lasting prohibition to the subsystem's constraints, and stop - no card (GCF-PRD §6.3)
+4. copy `templates/card.md` to `gcf/cards/<card-id>-<slug>.md`: the id keeps the candidate number, or takes the next free number for a fresh idea
+5. fill the frontmatter: status proposed, route, system list from the INDEX vocabulary, depends from cards this feature builds on, source, created
+6. fill the six slots with the human: behavior, contract, feel (comparison + envelopes), interactions, constraints, miss_criterion
+7. when the card came from a candidate, delete that candidate line from `gcf/backlog.md`
+8. run `ai-factory gcf index`, then `npx cnlp check`, and fix what they report
+9. report the card path and the one question the playtest will answer
+
+invocation:
+- run when work starts on a feature or the user names a candidate to materialize

package/skills/gcf-debate/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: gcf-debate
+description: The debate table - expert lenses stress a GDD for gaps, contradictions and unbuildable specs before import. Use when the user asks to review a GDD, check design coherence, or says "стол дебатов".
+---
+
+mode: review board
+
+purpose:
+- stress a GDD through the GCF lenses and report the gaps the designer did not write down
+
+inputs:
+- a path to the GDD (markdown); optionally the names of lenses to run, default is all
+
+preconditions:
+- the file exists and is readable markdown
+
+forbidden_behaviors:
+- do not edit the document without the human's explicit go-ahead per edit
+- do not resolve a principal fork yourself: a fork goes to the human as a D1 question with a proposed default
+- do not review style or prose quality: the table checks buildability and coherence only
+
+workflow:
+1. run `ai-factory gcf anchor <file>` and use the printed anchors in every finding
+2. play each completeness lens as its own expert over each mechanic: state, input, feedback, refusal, boundaries, persistence (GCF-PRD §11.4)
+3. play the coherence lenses over the whole document: interaction matrix (which mechanics write the same state), loop closure, progression pressure, economy balance, one-word-per-concept dictionary
+4. cross-examine: for each pair of findings that touch one anchor, check whether they contradict each other and merge or escalate
+5. classify each finding: D2 gets a proposed default the human can skim; D1 is a principal fork and carries the question, the anchors and a proposed answer
+6. report by lens, ordered by damage: contradictions first, then holes, then dictionary drift; cite anchors, quote lines <= 15 words
+7. when `gcf/` exists, append D1 and D2 records to `gcf/open-questions.md`; otherwise put them into the report only
+8. offer the fixes: apply agreed edits to the document one by one, each on its own go-ahead
+
+invocation:
+- run on a fresh GDD before ingest, after a big GDD revision, or on demand

package/skills/gcf-ingest/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: gcf-ingest
+description: Import a GDD into GCF - anchors, candidate backlog, pillar candidates, gap questions; re-import classifies the delta. Use when the user brings a GDD or says "импортируй GDD".
+---
+
+mode: import
+
+purpose:
+- cut a GDD into inert backlog candidates and a short list of questions, without putting anyone "into work"
+
+inputs:
+- a path to the GDD (markdown)
+
+preconditions:
+- `gcf/` exists (run gcf-init first)
+- the sequential pass below is the correctness reference; the parallel fan-out belongs to the harness
+
+forbidden_behaviors:
+- do not create card files: candidates are backlog lines, a card materializes only at pull (GCF-PRD §5.2)
+- do not write a pillar into PILLARS.md: pillar candidates go to open-questions as D1
+- do not put an extracted unit into the backlog without a verbatim quote from its section: no quote means source inferred, and inferred goes to open-questions
+- do not read `gcf/source/` files whole after anchoring: address sections by anchor
+
+workflow:
+1. run `ai-factory gcf anchor <file>`; on a re-import read the printed delta and jump to step 9
+2. extract per aspect, one pass each, citing a quote and an anchor per unit: pillar candidates; subsystems (nouns); feature candidates (player verbs); numbers and progressions; platform and audience constraints
+3. verify provenance: a unit whose quote is not found verbatim in its section becomes `inferred` and moves to the question list
+4. turn each exact number into an envelope: value ± the `envelope_default_spread` from `gcf/config.yml`, marked assumed, listed for the human's skim
+5. run the completeness lenses per candidate and write gaps into the candidate line as `gaps:` notes - questions at import time go only to document-level findings
+6. run the coherence lenses over the whole set; build the interaction matrix and record `deps:` between candidates from it
+7. write the outputs: candidate lines into `gcf/backlog.md` (route guessed per GCF-PRD §6, human vetoes later); D1 and D2 records into `gcf/open-questions.md`; then run `ai-factory gcf index`
+8. mark a candidate whose nouns match the `purpose` or the `code` paths of an existing systems doc with `impl?` in its backlog line: on an adopted codebase the mechanic may already ship, and the human is the one who deletes the line
+9. on a re-import, apply the delta classes (GCF-PRD §11.6): added -> new candidates; changed -> mark `src-changed`, and D1 when an open card or a collapsed system cites the anchor; removed -> orphan marks; renamed -> update anchors in place
+10. report the package, ordered: D1 questions (the main product), pillar candidates, dictionary conflicts, backlog summary with the top crossing candidates, D2 assumptions
+11. state the next step: answer D1s, confirm pillars, then pull the first candidate with `/gcf-card`
+
+invocation:
+- run when a GDD arrives or changes

package/skills/gcf-init/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: gcf-init
+description: Bootstrap the gcf/ documentary layer - skeleton, pillars interview, hooks reminder. Use when a game project adopts GCF or when the user says "set up gcf".
+---
+
+mode: bootstrap
+
+purpose:
+- create the gcf/ documentary layer and draft PILLARS.md from a short interview with the human
+
+inputs:
+- none: the skill discovers project state from the working directory and asks the human for the rest
+
+preconditions:
+- the project is a git repository with AI Factory initialized
+
+forbidden_behaviors:
+- do not overwrite an existing gcf/ tree: re-running repairs missing files only
+- do not write pillars the human did not confirm: pillar authorship is human (GCF-PRD §5.3)
+- pillar count <= 7, and do not pad the list to reach 7
+
+workflow:
+1. run `ai-factory gcf init` and report which files it created
+2. read `gcf/PILLARS.md`; when it still holds template content, start the interview
+3. ask the human for the game's core promise, then for 2..7 pillars: each needs a statement, a negative invariant and a review question
+4. rewrite `gcf/PILLARS.md` with the confirmed pillars in the pillars record-list form
+5. run `npx cnlp check` and fix form issues it reports
+6. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
+7. state the next step: fill `gcf/backlog.md` with candidates by hand or import a GDD
+
+invocation:
+- run when the user asks to set up gcf in a project

package/skills/gcf-verdict/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: gcf-verdict
+description: Record the human playtest verdict on a built card - keep, tune or kill - and run the collapse. Use after a playtest or when the user says "вердикт".
+---
+
+mode: human gate
+
+purpose:
+- record the human verdict and run the one operation that collapses a card into subsystem state
+
+inputs:
+- a card-NNN id and a verdict word: keep, tune or kill; or nothing, which means "print the playtest list"
+
+preconditions:
+- the card sits in status `built`; the human has played the build
+
+forbidden_behaviors:
+- do not decide the verdict: the human with hands on the controls decides, this skill records
+- do not run `keep` when the human has not answered the card's miss_criterion question
+- do not edit systems docs by hand: `ai-factory gcf verdict` owns the collapse
+
+workflow:
+1. with no arguments: run `ai-factory gcf playtest` and stop - that list is the session's playtest sheet
+2. read the card; ask the human the miss_criterion question and record the answer in one line
+3. for `tune` at tune_count 3: refuse and present the fork - kill, or redesign the envelope and reset the counter with a note (GCF-PRD §7.2)
+4. for `keep`: rewrite the behavior slot into 1 line per observable behavior and strip contract lines down to paths and entry points - the collapse copies lines verbatim, so compress them in the card first
+5. run `ai-factory gcf verdict <card-id> <verdict> --note "<answer or reason>"`
+6. for `keep` on a card touching 2 or more subsystems: read each updated systems doc and report a contradiction between constraints as a D1 question instead of finishing silently
+7. report the verdict commit hash: `git revert <hash>` is the undo
+
+invocation:
+- run after a playtest, or with no arguments to print the playtest sheet

package/skills/gcf-vision/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: gcf-vision
+description: Project-start wizard - guided questions that turn a raw game idea into a first GDD draft ready for gcf-ingest. Use when there is no project yet or the user says "начнем игру" / "start a game".
+---
+
+mode: wizard
+
+purpose:
+- turn a raw idea into a first GDD draft through a guided interview, so the standard ingest flow has an input
+
+inputs:
+- none: the skill discovers everything by asking the human
+
+preconditions:
+- no GDD exists yet; when one exists, route to gcf-debate or gcf-ingest instead
+
+forbidden_behaviors:
+- do not write into `gcf/`: the draft is the designer's document, ingest brings it into gcf later
+- do not fill an answer the human skipped: write the gap into the draft as an open question
+- questions per message <= 2: a wall of questions kills the interview
+
+workflow:
+1. ask about the core: genre, the one-sentence fantasy, and the reference games with "like X, not like Y"
+2. ask about the loop: what the player does each 30 seconds, each session, each week
+3. ask about scope: platform, session length, solo or multiplayer, art constraints, team size
+4. ask what the game is NOT: negative answers seed the pillars and cost the least
+5. draft the GDD as plain markdown with one `##` heading per topic: vision, pillars-candidates, core loop, mechanics, progression, scope, open questions
+6. write every unanswered or invented point into the `## open questions` section, marked as a guess
+7. present the draft, iterate on the human's corrections, and save where the human names
+8. state the next step: `/gcf-debate <file>` to stress the draft, or `/gcf-ingest <file>` to import it
+
+invocation:
+- run at project start, before any gcf structure exists

package/templates/PILLARS.md

@@ -0,0 +1,8 @@
+pillars:
+- statement: every encounter is readable at a glance
+  invariant: no effect ever hides the player character
+  review_question: does this change add visual noise over the player
+
+- statement: death is the player's fault, never the camera's
+  invariant: no off-screen damage sources
+  review_question: can this change hurt the player from outside the view

package/templates/backlog.md

@@ -0,0 +1,4 @@
+# Backlog — candidates, one line each. Order = priority, owned by the human.
+# Format: - <cand-id> | <name> | route: soft|hard | sys: <system> | deps: <ids or -> | src: <GDD#id|manual> | <one-line description>
+
+- cand-001 | example move | route: soft | sys: example-system | deps: - | src: manual | the move this template illustrates

package/templates/card.md

@@ -0,0 +1,34 @@
+---
+schema: 1
+id: card-000
+slug: example
+status: proposed
+route: soft
+system: [example-system]
+depends: []
+source: manual
+tune_count: 0
+built_at: null
+created: "2026-01-01"
+---
+
+behavior:
+- player presses X -> the character does Y -> the screen shows Z
+
+contract:
+- new components and systems live under Assets/Scripts/Example/
+- data flows from input to simulation, never backwards
+
+feel:
+- like Hades, not like Celeste
+- duration 0.15..0.25 s
+- cooldown 0.4..0.8 s
+
+interactions:
+- none: this example crosses no existing mechanic
+
+constraints:
+- do not add a new input binding
+- no per-frame allocations
+
+miss_criterion: does the move feel responsive on the first try

package/templates/cnlp.config.json

@@ -0,0 +1,8 @@
+{
+  "profiles": ".ai-factory/extensions/gcf-aif-ext/profiles",
+  "corpus": [
+    { "profile": "card", "glob": "gcf/cards/*.md" },
+    { "profile": "system", "glob": "gcf/systems/*.md" },
+    { "profile": "pillars", "glob": "gcf/PILLARS.md" }
+  ]
+}

package/templates/config.yml

@@ -0,0 +1,8 @@
+schema: 1
+built_stale_after_commits: 5
+tune_limit: 3
+question_stale_after_commits: 20
+wip_built_limit: 5
+context_budget: 30000
+pillars_budget: 1500
+envelope_default_spread: 0.3

package/templates/system.md

@@ -0,0 +1,22 @@
+---
+system: example-system
+updated_by: card-000
+---
+
+purpose:
+- holds the example mechanic and its simulation rules
+
+code:
+- Assets/Scripts/Example/, entry point ExampleFeature.cs
+
+behavior:
+- pressing X performs Y with feedback Z
+
+feel:
+- duration 0.15..0.25 s, kept as the retune envelope
+
+constraints:
+- do not stop the simulation from this subsystem
+
+open:
+- tempo assumption pending combat retune [until: retune(combat)]