@codebehind/agent-workflow 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +94 -0
  2. package/bin/agent-workflow.mjs +96 -0
  3. package/package.json +28 -0
  4. package/templates/.agent-workflow/README.md +160 -0
  5. package/templates/.agent-workflow/acceptance-verification.md +192 -0
  6. package/templates/.agent-workflow/artifacts/.gitkeep +0 -0
  7. package/templates/.agent-workflow/docs/README.md +45 -0
  8. package/templates/.agent-workflow/docs/_template.md +35 -0
  9. package/templates/.agent-workflow/notion-spec-mapping.md +54 -0
  10. package/templates/.agent-workflow/plans/.gitkeep +0 -0
  11. package/templates/.agent-workflow/plans/README.md +19 -0
  12. package/templates/.agent-workflow/playwright-acceptance.md +169 -0
  13. package/templates/.agent-workflow/specs/README.md +46 -0
  14. package/templates/.agent-workflow/specs/_template.md +60 -0
  15. package/templates/.agent-workflow/specs/assets/.gitkeep +0 -0
  16. package/templates/.agent-workflow/specs/assets/README.md +15 -0
  17. package/templates/.claude/hooks/.gitkeep +0 -0
  18. package/templates/.claude/rules/agentic-workflow.md +138 -0
  19. package/templates/.claude/settings.json +76 -0
  20. package/templates/.claude/skills/acceptance-proof/SKILL.md +68 -0
  21. package/templates/.claude/skills/create-mr-summary/SKILL.md +29 -0
  22. package/templates/.claude/skills/implement-spec/SKILL.md +97 -0
  23. package/templates/.claude/skills/prepare-spec/SKILL.md +77 -0
  24. package/templates/AGENTS.md +43 -0
  25. package/templates/agents-workflow-dev-process.md +212 -0
  26. package/templates/agents-workflow-env-setup.md +136 -0
  27. package/templates/scripts/agent/LOCAL_GITLAB_WORKFLOW.md +83 -0
  28. package/templates/scripts/agent/cleanup-worktree.sh +23 -0
  29. package/templates/scripts/agent/ensure-codebase.sh +43 -0
  30. package/templates/scripts/agent/git-detect-default-branch.sh +32 -0
  31. package/templates/scripts/agent/git-find-open-mr.sh +6 -0
  32. package/templates/scripts/agent/git-open-mr.sh +24 -0
  33. package/templates/scripts/agent/git-prepare-worktree.sh +54 -0
  34. package/templates/scripts/agent/git-push-branch.sh +12 -0
  35. package/templates/scripts/agent/git-update-mr.sh +28 -0
  36. package/templates/scripts/agent/implement-task.sh +19 -0
  37. package/templates/scripts/agent/mr-template.sh +33 -0
  38. package/templates/scripts/agent/post-run-summary.sh +24 -0
  39. package/templates/scripts/agent/prepare-spec.sh +19 -0
  40. package/templates/scripts/agent/start-worktree.sh +36 -0
  41. package/templates/scripts/agent/verify-acceptance.sh +12 -0
package/README.md ADDED
@@ -0,0 +1,94 @@
1
+ # @codebehind/agent-workflow
2
+
3
+ A scaffolding CLI that installs the **agent-workflow** spec-driven delivery framework into any repository.
4
+
5
+ The framework gives AI agents (Claude Code) a structured way to work: write specs, plan implementations, verify acceptance criteria, and hand off via GitLab merge requests — all with human checkpoints where you want them.
6
+
7
+ ---
8
+
9
+ ## Quick start
10
+
11
+ ```bash
12
+ npx @codebehind/agent-workflow init
13
+ ```
14
+
15
+ Run this from the root of any repo (meta repo, monorepo, or single-purpose repo). It copies the full framework into place and prints next steps.
16
+
17
+ Use `--force` to overwrite existing files:
18
+
19
+ ```bash
20
+ npx @codebehind/agent-workflow init --force
21
+ ```
22
+
23
+ ---
24
+
25
+ ## What gets installed
26
+
27
+ ```
28
+ .agent-workflow/
29
+ README.md ← workflow rules for agents
30
+ acceptance-verification.md ← acceptance proof protocol
31
+ playwright-acceptance.md ← UI verification guide
32
+ notion-spec-mapping.md ← Notion → spec mapping rules
33
+ specs/_template.md ← spec template
34
+ plans/ ← agent-generated plans
35
+ docs/ ← feature documentation
36
+ artifacts/ ← acceptance proof artifacts
37
+
38
+ .claude/
39
+ rules/agentic-workflow.md ← Claude Code session rules
40
+ settings.json ← permissions config
41
+ skills/
42
+ prepare-spec/SKILL.md ← /prepare-spec skill
43
+ implement-spec/SKILL.md ← /implement-spec skill
44
+ acceptance-proof/SKILL.md ← /acceptance-proof skill
45
+ create-mr-summary/SKILL.md ← /create-mr-summary skill
46
+
47
+ scripts/agent/ ← GitLab helper scripts (glab-based)
48
+
49
+ AGENTS.md ← agent onboarding instructions
50
+ agents-workflow-dev-process.md ← human user manual
51
+ agents-workflow-env-setup.md ← one-time environment setup guide
52
+ ```
53
+
54
+ ---
55
+
56
+ ## Workflow overview
57
+
58
+ | Phase | What happens | Skill |
59
+ |-------|-------------|-------|
60
+ | A — Prepare spec | Create or refine a spec (`draft`) | `/prepare-spec` |
61
+ | B — Implement spec | Plan → code → docs for an `open` spec | `/implement-spec` |
62
+
63
+ See `agents-workflow-dev-process.md` after init for the full Claude Code workflow.
64
+
65
+ ---
66
+
67
+ ## After init
68
+
69
+ 1. **Customize** `AGENTS.md` and `agents-workflow-dev-process.md` for your project context.
70
+ 2. **Add a `CLAUDE.md`** at the repo root with project-specific AI instructions (domain, architecture, conventions).
71
+ 3. **Make scripts executable**: `chmod +x scripts/agent/*.sh`
72
+ 4. **Install prerequisites**: `glab`, `jq`, `node >= 18` — see `agents-workflow-env-setup.md`.
73
+ 5. **Write your first spec**: copy `.agent-workflow/specs/_template.md` to `.agent-workflow/specs/my-feature.md`.
74
+
75
+ ---
76
+
77
+ ## Requirements
78
+
79
+ - Node.js 18+
80
+ - `glab` (GitLab CLI) for MR management
81
+ - `jq`
82
+ - Claude Code CLI
83
+
84
+ ---
85
+
86
+ ## Versioning
87
+
88
+ This package follows semver. Breaking changes to the framework structure increment the major version. To upgrade an existing installation:
89
+
90
+ ```bash
91
+ npx @codebehind/agent-workflow init --force
92
+ ```
93
+
94
+ Review the diff carefully — files you've customized for your project will be overwritten.
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env node
2
+ import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync } from 'fs';
3
+ import { join, dirname, relative } from 'path';
4
+ import { fileURLToPath } from 'url';
5
+
6
+ const __dirname = dirname(fileURLToPath(import.meta.url));
7
+ const TEMPLATES_DIR = join(__dirname, '..', 'templates');
8
+ const VERSION = '1.0.0';
9
+
10
+ const args = process.argv.slice(2);
11
+ const command = args[0];
12
+ const force = args.includes('--force');
13
+
14
+ function printUsage() {
15
+ console.log(`
16
+ @codebehind/agent-workflow v${VERSION}
17
+
18
+ Usage:
19
+ npx @codebehind/agent-workflow init [--force]
20
+
21
+ Commands:
22
+ init Copy the agent-workflow framework files into the current directory.
23
+ Skips files that already exist (use --force to overwrite).
24
+
25
+ Options:
26
+ --force Overwrite existing files.
27
+ --version Print version and exit.
28
+ `);
29
+ }
30
+
31
+ function walkDir(dir, baseDir, callback) {
32
+ for (const entry of readdirSync(dir)) {
33
+ const fullPath = join(dir, entry);
34
+ const relPath = relative(baseDir, fullPath);
35
+ if (statSync(fullPath).isDirectory()) {
36
+ walkDir(fullPath, baseDir, callback);
37
+ } else {
38
+ callback(fullPath, relPath);
39
+ }
40
+ }
41
+ }
42
+
43
+ function init(targetDir) {
44
+ const copied = [];
45
+ const skipped = [];
46
+
47
+ walkDir(TEMPLATES_DIR, TEMPLATES_DIR, (srcPath, relPath) => {
48
+ const destPath = join(targetDir, relPath);
49
+ const destDir = dirname(destPath);
50
+
51
+ if (!force && existsSync(destPath)) {
52
+ skipped.push(relPath);
53
+ return;
54
+ }
55
+
56
+ mkdirSync(destDir, { recursive: true });
57
+ copyFileSync(srcPath, destPath);
58
+ copied.push(relPath);
59
+ });
60
+
61
+ if (copied.length > 0) {
62
+ console.log('\nCopied:');
63
+ for (const f of copied) console.log(` + ${f}`);
64
+ }
65
+
66
+ if (skipped.length > 0) {
67
+ console.log('\nSkipped (already exist — use --force to overwrite):');
68
+ for (const f of skipped) console.log(` ~ ${f}`);
69
+ }
70
+
71
+ console.log(`
72
+ Done. ${copied.length} file(s) copied, ${skipped.length} skipped.
73
+
74
+ Next steps:
75
+ 1. Customize AGENTS.md and agents-workflow-dev-process.md for your project.
76
+ 2. Add a CLAUDE.md at the repo root with project-specific AI instructions.
77
+ 3. If this is a meta repo with submodules, add them:
78
+ git submodule add <url> <folder>
79
+ 4. Review .claude/settings.json and adjust permissions as needed.
80
+ 5. Make agent scripts executable:
81
+ chmod +x scripts/agent/*.sh
82
+ 6. See agents-workflow-env-setup.md for full setup instructions.
83
+ `);
84
+ }
85
+
86
+ // Entry point
87
+ if (command === '--version' || command === '-v') {
88
+ console.log(VERSION);
89
+ process.exit(0);
90
+ } else if (!command || command === 'init') {
91
+ init(process.cwd());
92
+ } else {
93
+ console.error(`Unknown command: ${command}`);
94
+ printUsage();
95
+ process.exit(1);
96
+ }
package/package.json ADDED
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "@codebehind/agent-workflow",
3
+ "version": "1.0.0",
4
+ "description": "Scaffold the agent-workflow spec-driven delivery framework into any repo",
5
+ "type": "module",
6
+ "bin": {
7
+ "agent-workflow": "bin/agent-workflow.mjs"
8
+ },
9
+ "files": [
10
+ "bin/",
11
+ "templates/"
12
+ ],
13
+ "engines": {
14
+ "node": ">=18"
15
+ },
16
+ "license": "MIT",
17
+ "keywords": [
18
+ "claude-code",
19
+ "ai-agent",
20
+ "workflow",
21
+ "scaffold",
22
+ "spec-driven"
23
+ ],
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git+https://gitlab.com/codebehind/agent-workflow.git"
27
+ }
28
+ }
@@ -0,0 +1,160 @@
1
+ # Agent Workflow
2
+
3
+ This folder contains the complete feature delivery workflow for both Users and Agents.
4
+
5
+ ## Target Structure
6
+
7
+ ```mermaid
8
+ flowchart TD
9
+ User["User"] --> Specs[".agent-workflow/specs/"]
10
+ AgentPlan["Agent (Plan mode)"] --> Plans[".agent-workflow/plans/"]
11
+ AgentImpl["Agent (Agent mode)"] --> Docs[".agent-workflow/docs/"]
12
+ RootReadme[".agent-workflow/README.md"] --> User
13
+ RootReadme --> AgentPlan
14
+ RootReadme --> AgentImpl
15
+ ```
16
+
17
+ ## Spec status
18
+
19
+ | Value | Meaning |
20
+ |--------|--------|
21
+ | `draft` | Spec file exists; **not** ready for implementation. User or agent is still authoring. |
22
+ | `open` | Ready for Phase B: planning, implementation, docs. |
23
+ | `done` | Delivered; agent sets this after the feature doc is written and work is complete. |
24
+
25
+ Additional frontmatter fields:
26
+
27
+ | Field | Default | Meaning |
28
+ |-------|---------|---------|
29
+ | `verification` | `true` | Human checkpoints during Phase B (`true` = plan/impl approval; `false` = autonomous). |
30
+ | `acceptance_proof` | `true` | Acceptance verification capture after implementation (`true` = required; `false` = skip capture, post text-only confirmation instead — use only for pure config/infra specs with no visual or API surface). |
31
+
32
+ **Rule:** Phase B (implementation) only targets specs with **`status: open`**. Ignore **`draft`** unless the user explicitly asked to edit the spec, not implement the feature.
33
+
34
+ ---
35
+
36
+ ## Phase A — Spec authorship
37
+
38
+ How the spec file gets into `./specs/`:
39
+
40
+ 1. **1.1 User-written:** User copies `./specs/_template.md`, fills it in, sets `status` to `draft` or `open`, commits, and tells the agent when ready (local chat or Slack for Cloud Agents).
41
+ 2. **1.2 Chat-only drafting:** Agent uses **plan-style** interaction (outline, questions, suggestions) until the user agrees, then writes `./specs/{name}.md`, usually with **`status: draft`**.
42
+ 3. **1.3 From Notion:** Agent uses Notion MCP (`notion-fetch`), maps content using [`.agent-workflow/notion-spec-mapping.md`](notion-spec-mapping.md), asks questions, proposes a spec outline (**plan-style**) until the user agrees, then writes the spec file, usually **`status: draft`**.
43
+ 4. **1.4 Triggers:** User may paste a Notion URL or a free-text description (local or Slack — see repo root `agents-workflow-dev-process.md` for Slack patterns). **Prepare-spec** work belongs in a **dedicated Slack thread** (Thread A) separate from implementation (Thread B).
44
+ 5. **1.5 Agent output:** Spec is saved under `./specs/`; agent informs the user (chat or Slack) with the file path.
45
+ 6. **1.6 User review:** User edits the spec and/or sets **`status: open`** when development should start (or asks the agent to flip `draft` → `open`).
46
+
47
+ Frontmatter for new specs: `verification: true|false` (default **`true`** if omitted in Phase B). Notion-sourced specs may include optional `notion_source` / `scope` — see `notion-spec-mapping.md`.
48
+
49
+ ---
50
+
51
+ ## Phase B — Delivery (implementation)
52
+
53
+ 1. **Agent reads the spec** with **`status: open`** and creates a plan in `./plans/` named `{spec-name}_plan.md`.
54
+ 2. **Agent checks verification mode** (default `verification: true` when missing):
55
+ - `verification: true`: standard checkpoints (plan approval + implementation approval).
56
+ - `verification: false`: continue autonomously after plan creation.
57
+ 3. **Agent implements** the feature.
58
+ 4. **Agent verifies acceptance criteria** — reads each `- [ ]` item from the spec, captures **runtime proof** (Playwright-first screenshots for UI, `curl` output for API) following [`.agent-workflow/acceptance-verification.md`](acceptance-verification.md) and [`.agent-workflow/playwright-acceptance.md`](playwright-acceptance.md), saves artifacts under `.agent-workflow/artifacts/`, and includes the acceptance checklist in the MR description. MR is **not** opened until all criteria pass (or blocked criteria are explicitly documented).
59
+ 5. **Agent writes/updates** the final feature document in `./docs/` using `./docs/_template.md`.
60
+ 6. **Agent marks the spec** `status: done`.
61
+
62
+ ```mermaid
63
+ flowchart TD
64
+ subgraph authorship [Phase A Spec authorship]
65
+ U1[User or Agent creates spec]
66
+ U1 --> DraftFile["specs/*.md status draft"]
67
+ DraftFile --> UserReview[User review]
68
+ UserReview --> OpenSpec["status open"]
69
+ end
70
+ subgraph delivery [Phase B Delivery]
71
+ OpenSpec --> Plan["plans/"]
72
+ Plan --> Impl[Implementation]
73
+ Impl --> Verify["Verify acceptance criteria\n+ post proof to Slack"]
74
+ Verify --> Docs["docs/"]
75
+ Docs --> Done[status done + MR opened]
76
+ end
77
+ ```
78
+
79
+ ---
80
+
81
+ ## Feature Doc Selection Rule
82
+
83
+ When writing final documentation, choose update/create in this order:
84
+
85
+ 1. If an existing feature doc already lists the spec under `Covered Specs`, update that doc.
86
+ 2. Else if one existing doc clearly matches the same bounded context (same page/domain/integration/data entities), update that doc.
87
+ 3. Else create a new feature doc from `./docs/_template.md`.
88
+ 4. Always add the spec under `Covered Specs` in the selected/new doc.
89
+
90
+ ---
91
+
92
+ ## Codebase Snapshot
93
+
94
+ To reduce onboarding cost, use a reusable codebase snapshot file:
95
+
96
+ - Path: `.agent-workflow/codebase.md`
97
+ - If the file is missing, the first onboarded agent scans the codebase and creates it.
98
+ - If the file exists, agents read it instead of rescanning the codebase.
99
+ - Rescan and refresh this file only when the user explicitly asks.
100
+
101
+ Expected snapshot structure (keep concise and high-level):
102
+
103
+ 1. Project Overview
104
+ 2. Backend Structure
105
+ 3. Frontend Structure
106
+ 4. Data/DB Layer
107
+ 5. API Surface Summary
108
+ 6. Feature Workflow Files
109
+ 7. Key Commands
110
+
111
+ ---
112
+
113
+ ## Ad-hoc Changes
114
+
115
+ For non-trivial changes not described by a new feature spec:
116
+
117
+ - Document the change in the relevant feature doc's **Change Log** in `./docs/`.
118
+ - Agent and User should agree which feature document should be updated.
119
+ - Trivial cosmetic tweaks (for example color and icon swaps) can skip documentation.
120
+
121
+ ---
122
+
123
+ ## Naming Rules
124
+
125
+ - Specs: `./specs/{name}.md`
126
+ - Plans: `./plans/{spec-name}_plan.md`
127
+ - Feature docs: `./docs/{descriptive-feature-name}.md`
128
+
129
+ ---
130
+
131
+ ## Onboarding
132
+
133
+ - **Users:** Add specs under `./specs/` using `_template.md`. Use **`draft`** until ready, then **`open`** for implementation. See `agents-workflow-dev-process.md` for the full Claude Code workflow (skill invocations, worktrees, MR flow). Set `verification: false` when you want autonomous execution without verification checkpoints in Phase B.
134
+ - **Agents:**
135
+ 1. Read this file first.
136
+ 2. Check `.agent-workflow/codebase.md`.
137
+ 3. If missing, create it by scanning the codebase once. If present, read it and continue.
138
+ 4. If the task is **prepare spec** (Notion URL, chat drafting): follow Phase A; write **`draft`** unless the user says otherwise.
139
+ 5. If the task is **implement feature**: read `verification` in each relevant spec with **`status: open`** (default `true` when missing).
140
+ 6. Continue with `./specs/`, `./plans/`, and `./docs/` according to Phase B above.
141
+ 7. **After implementation:** always run the acceptance verification step per [`.agent-workflow/acceptance-verification.md`](acceptance-verification.md) (unless `acceptance_proof: false` in the spec). For UI tasks, use the Playwright-first guidance in [`.agent-workflow/playwright-acceptance.md`](playwright-acceptance.md). Include proof in the MR description before opening it.
142
+
143
+ ---
144
+
145
+ ## Meta-repo specifics
146
+
147
+ This is the project's meta repository. The `.agent-workflow/` directory exists **only here** — there are no per-submodule workflow directories.
148
+
149
+ | Content | Location |
150
+ |---------|---------|
151
+ | Specs, plans, feature docs, artifacts | This repo under `.agent-workflow/` |
152
+ | Backend application code | `backend/` submodule — commit and MR in project-backend |
153
+ | Web application code | `web/` submodule — commit and MR in project-web |
154
+ | Mobile application code | `mobile/` submodule — commit and MR in project-mobile |
155
+
156
+ When implementing a spec that touches application code:
157
+ 1. Navigate into the relevant submodule directory to make code changes.
158
+ 2. Open a separate MR in that submodule's GitLab project.
159
+ 3. The meta repo MR covers only spec, plan, docs, and artifacts.
160
+ 4. Reference the submodule MR(s) in the meta repo MR description.
@@ -0,0 +1,192 @@
1
+ # Acceptance Verification Protocol
2
+
3
+ This document defines how agents **verify acceptance criteria and report proof** at the end of Phase B, before opening an MR.
4
+
5
+ ---
6
+
7
+ ## Meta-repo note
8
+
9
+ This is the project's meta repository. Application code lives in submodules (for example `backend/`, `web/`, `mobile/`). Acceptance proof that requires a running app (UI screenshots, API curl) must be executed **inside the relevant submodule directory**. Artifacts are then saved here under `.agent-workflow/artifacts/`.
10
+
11
+ ---
12
+
13
+ ## Core rule
14
+
15
+ Acceptance proof must show **what ran**, **what was observed**, and **where the evidence lives**.
16
+
17
+ Do not confuse these three ideas:
18
+
19
+ - **Implemented** — code was written
20
+ - **Verified automatically** — runtime checks actually ran
21
+ - **Human QA** — reviewer or tester still checked behavior manually
22
+
23
+ A statement such as “`onRowClick` was added” is implementation evidence, not acceptance evidence.
24
+
25
+ ---
26
+
27
+ ## When to run
28
+
29
+ After implementation is complete, **before writing docs or opening the MR**, the agent must:
30
+
31
+ 1. Read every `- [ ]` item from the `### Acceptance Criteria` section of the spec.
32
+ 2. Check `acceptance_proof` in the spec's YAML frontmatter (default `true` when missing).
33
+ - `acceptance_proof: false` — skip capture and post a brief text-only confirmation instead.
34
+ - `acceptance_proof: true` (or missing) — full capture required.
35
+ 3. Create the artifact folder manually:
36
+
37
+ ```bash
38
+ mkdir -p .agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>
39
+ ```
40
+
41
+ 4. Classify each criterion (see below), capture proof, save artifacts, and prepare the MR handoff.
42
+
43
+ ---
44
+
45
+ ## Classifying each criterion
46
+
47
+ | Criterion type | How to identify | Capture method |
48
+ |----------------|----------------|----------------|
49
+ | **UI / visual** | Involves a page, component, user interaction, tab, layout, or rendered output | **Playwright-first** browser run + screenshots (video/trace optional) |
50
+ | **API / data** | Involves an HTTP endpoint, data shape, or server response | `curl` against the local server; terminal output or saved `.txt` |
51
+ | **Config / infra** | Build flags, env vars, CI config, no runtime surface | Text confirmation + relevant log or build output |
52
+
53
+ A single criterion may need both UI and API evidence.
54
+
55
+ ---
56
+
57
+ ## Required status fields per criterion
58
+
59
+ Every criterion entry in `acceptance-summary.md` must include:
60
+
61
+ - **Classification** — `ui`, `api`, or `config`
62
+ - **Code status** — `implemented` or `not implemented`
63
+ - **Automated verification** — `passed`, `failed`, or `not run`
64
+ - **Human verification** — usually `pending` unless a human already checked it
65
+ - **Evidence paths** — screenshot / video / curl / log path(s)
66
+ - **Notes** — blockers, caveats, chosen fixture data, or observed differences
67
+
68
+ This prevents reviewers from mistaking “implemented” for “tested”.
69
+
70
+ ---
71
+
72
+ ## How to capture proof
73
+
74
+ ### UI / visual criteria
75
+
76
+ For UI criteria, use **Playwright-first verification**. See `.agent-workflow/playwright-acceptance.md`.
77
+
78
+ Minimum expected evidence for a UI task:
79
+
80
+ 1. Start the app with the normal local dev flow.
81
+ 2. Open the page or flow in the browser automation tool.
82
+ 3. Assert the primary visible UI elements from the spec.
83
+ 4. Save screenshots for each meaningful state.
84
+ 5. Record the result in `acceptance-summary.md`.
85
+
86
+ Recommended screenshots for page-level UI tasks:
87
+
88
+ - route landing / entry point
89
+ - top summary section
90
+ - each important tab or subsection
91
+ - post-interaction result state
92
+ - empty or fallback state, if required by the spec
93
+
94
+ Good verification example:
95
+
96
+ > Playwright opened `/games`, clicked one row, navigated to `/games/:id`, confirmed the game summary title was visible, and saved `01-route-navigation.png`.
97
+
98
+ Bad verification example:
99
+
100
+ > Added `navigate('/games/${row.game_id}')` in the table click handler.
101
+
102
+ ### API / data criteria
103
+
104
+ 1. Ensure the local app is running.
105
+ 2. Run a `curl` command against the local server.
106
+ 3. Save either:
107
+ - terminal output into a `.txt` file under the artifact directory, or
108
+ - a readable code block in the final handoff.
109
+ 4. Record the exact endpoint and observed result in `acceptance-summary.md`.
110
+
111
+ Example pattern:
112
+
113
+ ```bash
114
+ curl -s http://localhost:3000/api/game/123/summary | jq . \
115
+ > .agent-workflow/artifacts/acceptance-example-20260329/02-game-summary-response.txt
116
+ ```
117
+
118
+ ### Config / infra criteria
119
+
120
+ 1. Run the relevant command (`npm run build`, `npm run lint`, etc.).
121
+ 2. Save the final useful output lines in a `.txt` file when practical.
122
+ 3. Record whether the criterion was actually exercised or only inspected statically.
123
+
124
+ ---
125
+
126
+ ## Artifact naming
127
+
128
+ Save all files under:
129
+
130
+ ```text
131
+ .agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/
132
+ ```
133
+
134
+ Suggested file naming inside that folder:
135
+
136
+ ```text
137
+ acceptance-summary.md
138
+ 01-<criterion-slug>.png
139
+ 02-<criterion-slug>.txt
140
+ 03-<criterion-slug>.webm
141
+ ```
142
+
143
+ Where:
144
+ - `<spec-slug>` is the spec filename without the date prefix and `.md`
145
+ - `<YYYYMMDD>` is the run date
146
+ - the numeric prefix matches the order of the acceptance criteria in the spec
147
+
148
+ Keep artifacts concise and reviewer-friendly.
149
+
150
+ ---
151
+
152
+ ## MR handoff
153
+
154
+ Include an acceptance checklist in the MR description. Format:
155
+
156
+ ```
157
+ ## Acceptance verification
158
+
159
+ ✓ 01 — <criterion text> — [evidence](artifacts/...)
160
+ ✓ 02 — <criterion text> — [evidence](artifacts/...)
161
+ ⚠ 03 — SKIPPED — <reason; manual verification required>
162
+ ✗ 04 — FAILED — <what failed and what was done to fix it>
163
+ ```
164
+
165
+ - pass / fail / skipped per criterion
166
+ - relative links to artifact files where applicable
167
+ - short notes for any failure or manual follow-up
168
+
169
+ ---
170
+
171
+ ## Blocking rule
172
+
173
+ - **All criteria pass** → proceed to docs, mark spec `done`, and open the MR.
174
+ - **Any criterion fails** → record the failure clearly, fix it, and re-run the affected verification.
175
+ - **Untestable locally** → mark as `skipped`, explain why, and specify the manual verification step required.
176
+
177
+ Never present a criterion as passed when the runtime check was not actually executed.
178
+
179
+ ---
180
+
181
+ ## Quick checklist for agents
182
+
183
+ Before opening the MR, confirm:
184
+
185
+ - [ ] `acceptance_proof` is not `false` in the spec (or text-only confirmation was intentional)
186
+ - [ ] artifact folder created at `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/`
187
+ - [ ] every criterion has `classification`, `code status`, `automated verification`, `human verification`, and `evidence paths`
188
+ - [ ] UI criteria have Playwright-first browser evidence
189
+ - [ ] API criteria have request/response evidence
190
+ - [ ] artifacts are saved under `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/`
191
+ - [ ] MR description includes the acceptance checklist with artifact links
192
+ - [ ] no failed criterion is hidden behind vague wording like “implemented”
File without changes
@@ -0,0 +1,45 @@
1
+ # Docs
2
+
3
+ This folder contains final feature documentation written after implementation is completed.
4
+
5
+ ## Source of Truth
6
+
7
+ Read `../README.md` first for the full workflow used by both Users and Agents.
8
+
9
+ ## Purpose
10
+
11
+ Feature docs provide a concise overview of:
12
+ - **Functional perspective** (stakeholders): value, behavior, and user impact
13
+ - **Technical perspective** (dev/QA): architecture, files, and data flow
14
+
15
+ ## Guidelines
16
+
17
+ - Use `_template.md` as the starting structure.
18
+ - Keep concise: about one A4 page for Functional and one for Technical.
19
+ - Do not include acceptance criteria, scenario matrices, or edge-case catalogs here.
20
+ - Track non-trivial follow-up changes in the **Change Log**.
21
+
22
+ ## For AI Agents
23
+
24
+ - Write/update docs after implementation is completed for the spec.
25
+ - Respect spec verification mode:
26
+ - `verification: true`: write/update docs after implementation approval checkpoint.
27
+ - `verification: false`: write/update docs autonomously (no approval checkpoint pause).
28
+ - Decide update/create in this order:
29
+ 1. If a doc already lists the spec in `Covered Specs`, update that doc.
30
+ 2. Else if one existing doc clearly matches the same bounded context, update that doc.
31
+ 3. Else create a new doc from `_template.md`.
32
+ 4. Add the spec to `Covered Specs` in the selected/new doc.
33
+ - For ad-hoc non-trivial changes, update the relevant feature doc Change Log after agreeing with the User which document to update.
34
+
35
+ ## Current Feature Docs
36
+
37
+ - [Fix Full Graphic Popup mobile responsiveness](./fix-full-graphic-popup-mobile-responsiveness.md)
38
+ - [Content page metadata](./content-page-metadata.md)
39
+ - [Sitemap API proxy](./sitemap-api-proxy.md)
40
+ - [Content 301 redirects](./content-301-redirects.md)
41
+ - [RapidAPI Integration And Sync](./rapidapi-integration-and-sync.md)
42
+ - [Match Predictor Data Enrichment](./match-predictor-data-enrichment.md)
43
+ - [H2H Comparison Features](./h2h-comparison-features.md)
44
+ - [Team And Last Games Features](./team-and-last-games-features.md)
45
+ - [Schedule And Prediction Assistant UX](./schedule-and-prediction-assistant-ux.md)
@@ -0,0 +1,35 @@
1
+ # {Feature Title}
2
+
3
+ ## Functional Overview
4
+
5
+ ### Goal / Value
6
+
7
+ The purpose and value of this feature in the context of the overall software, from a stakeholder perspective. What problem does it solve and why does it matter?
8
+
9
+ ### What it does
10
+
11
+ Brief description of the feature from a user/stakeholder perspective.
12
+
13
+ ### How it works
14
+
15
+ Step-by-step user flow or behavior description.
16
+
17
+ ## Technical Overview
18
+
19
+ ### Architecture
20
+
21
+ High-level description of components involved (backend endpoints, frontend pages, database tables, external integrations).
22
+
23
+ ### Key Files
24
+
25
+ List of primary files added or modified.
26
+
27
+ ### Data Flow
28
+
29
+ Brief description of how data moves through the system for this feature.
30
+
31
+ ## Change Log
32
+
33
+ | Date | Description |
34
+ |------|-------------|
35
+ | YYYY-MM-DD | Initial implementation |