@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.
- package/README.md +94 -0
- package/bin/agent-workflow.mjs +96 -0
- package/package.json +28 -0
- package/templates/.agent-workflow/README.md +160 -0
- package/templates/.agent-workflow/acceptance-verification.md +192 -0
- package/templates/.agent-workflow/artifacts/.gitkeep +0 -0
- package/templates/.agent-workflow/docs/README.md +45 -0
- package/templates/.agent-workflow/docs/_template.md +35 -0
- package/templates/.agent-workflow/notion-spec-mapping.md +54 -0
- package/templates/.agent-workflow/plans/.gitkeep +0 -0
- package/templates/.agent-workflow/plans/README.md +19 -0
- package/templates/.agent-workflow/playwright-acceptance.md +169 -0
- package/templates/.agent-workflow/specs/README.md +46 -0
- package/templates/.agent-workflow/specs/_template.md +60 -0
- package/templates/.agent-workflow/specs/assets/.gitkeep +0 -0
- package/templates/.agent-workflow/specs/assets/README.md +15 -0
- package/templates/.claude/hooks/.gitkeep +0 -0
- package/templates/.claude/rules/agentic-workflow.md +138 -0
- package/templates/.claude/settings.json +76 -0
- package/templates/.claude/skills/acceptance-proof/SKILL.md +68 -0
- package/templates/.claude/skills/create-mr-summary/SKILL.md +29 -0
- package/templates/.claude/skills/implement-spec/SKILL.md +97 -0
- package/templates/.claude/skills/prepare-spec/SKILL.md +77 -0
- package/templates/AGENTS.md +43 -0
- package/templates/agents-workflow-dev-process.md +212 -0
- package/templates/agents-workflow-env-setup.md +136 -0
- package/templates/scripts/agent/LOCAL_GITLAB_WORKFLOW.md +83 -0
- package/templates/scripts/agent/cleanup-worktree.sh +23 -0
- package/templates/scripts/agent/ensure-codebase.sh +43 -0
- package/templates/scripts/agent/git-detect-default-branch.sh +32 -0
- package/templates/scripts/agent/git-find-open-mr.sh +6 -0
- package/templates/scripts/agent/git-open-mr.sh +24 -0
- package/templates/scripts/agent/git-prepare-worktree.sh +54 -0
- package/templates/scripts/agent/git-push-branch.sh +12 -0
- package/templates/scripts/agent/git-update-mr.sh +28 -0
- package/templates/scripts/agent/implement-task.sh +19 -0
- package/templates/scripts/agent/mr-template.sh +33 -0
- package/templates/scripts/agent/post-run-summary.sh +24 -0
- package/templates/scripts/agent/prepare-spec.sh +19 -0
- package/templates/scripts/agent/start-worktree.sh +36 -0
- 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 |
|