@codebehind/agent-workflow 1.0.0

package/templates/.agent-workflow/notion-spec-mapping.md

@@ -0,0 +1,54 @@
+# Notion → spec template mapping
+
+This document defines how agents map **Notion** content into [`.agent-workflow/specs/_template.md`](specs/_template.md) when preparing a spec from a Notion URL (see Phase A in [`.agent-workflow/README.md`](README.md)).
+
+**Status:** Scaffold — extend the tables below with your team’s explicit mappings and examples. Agents should use **Notion MCP** (`notion-fetch`) to load the page, then apply the rules here.
+
+---
+
+## Defaults (frontmatter)
+
+When creating a spec from Notion, use these unless the user specifies otherwise:
+
+| Field | Default | Notes |
+|--------|---------|--------|
+| `status` | `draft` | User promotes to `open` when ready for implementation (Phase B). |
+| `verification` | `true` | Override if the user asks. |
+| `notion_source` | *(optional)* | Full Notion page URL for traceability. |
+| `scope` | *(optional)* | e.g. `frontend` / `backend` when one Notion page splits across repos (see below). |
+
+---
+
+## Section mapping (fill in)
+
+Map Notion blocks or headings to template sections. Mark each row **explicit** (strict) or **heuristic** (agent infers).
+
+| Notion (source) | Template section | Mapping type |
+|-----------------|------------------|--------------|
+| *(add rows)* | Title / Summary / Requirements / … | explicit \| heuristic |
+
+**Minimum content** agents should aim to fill (from Notion or clarification): **Title**, **Summary**, and **Acceptance Criteria** (or equivalent). Remaining sections: infer, mark as provisional, or leave with placeholders for the user.
+
+**Unmapped content:** Do not drop silently — place under **References** or **Notes (from Notion)** in the spec body.
+
+**Non-feature / incident / freeform pages:** Map to the nearest template sections; use **Goals** / **Non-Goals** with clear **(proposed)** labeling where needed.
+
+---
+
+## Multi-repo: one Notion page, several repositories
+
+One **feature** in Notion may produce **separate specs** in **different repos** (e.g. frontend app vs API/backend).
+
+- Each **repository** has its own `.agent-workflow/specs/*.md` and its own agent run.
+- Use the **same** `notion_source` URL in each spec when they derive from the same page.
+- **Scope** each spec to this codebase: include only requirements, APIs, or UI that belong in **this** repo; reference sibling work in **References** or **API / Data Contracts** as needed.
+- Two agents (two Slack threads / two branches) may run in parallel — one per repo — from the same Notion link with different scope instructions in chat.
+
+---
+
+## Agent checklist (Notion → spec file)
+
+1. `notion-fetch` the URL (or ID).
+2. Apply this mapping + [`.agent-workflow/README.md`](README.md) Phase A (plan-style: outline, questions, user agreement).
+3. Write `.agent-workflow/specs/{name}.md` from `_template.md`, typically `status: draft`.
+4. Tell the user the path and that they should review and set `status: open` when ready for development.

package/templates/.agent-workflow/plans/README.md

@@ -0,0 +1,19 @@
+# Plans
+
+This folder contains implementation plans created by the Agent during Plan mode.
+
+## Source of Truth
+
+Read `../README.md` first for the full workflow used by both Users and Agents.
+
+## Naming Convention
+
+```
+{feature-spec-filename}_plan.md
+```
+
+Example: spec `20260220_schedule_page.md` -> plan `20260220_schedule_page_plan.md`.
+
+## Format
+
+Plans are markdown and can be free-form, but should be clear and actionable.

package/templates/.agent-workflow/playwright-acceptance.md

@@ -0,0 +1,169 @@
+# Playwright Acceptance Instructions
+
+Use this guide when a spec has `acceptance_proof: true` and at least one acceptance criterion is UI / visual.
+
+## Goal
+
+Produce **runtime proof**, not just code references.
+
+For UI tasks, the minimum proof set is:
+- one automated browser run against the implemented flow
+- one screenshot for each important state or tab mentioned by the spec
+- a short acceptance summary that links each criterion to evidence
+
+## Required evidence standard
+
+The acceptance report must distinguish between these states:
+
+- **Implemented** — code exists
+- **Verified in browser** — Playwright opened the page and checked the UI
+- **Human QA pending** — still recommended for final review
+
+Do not collapse these into one status.
+
+## Recommended file layout
+
+Store proof under:
+
+```text
+.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/
+```
+
+Recommended sub-files:
+
+```text
+playwright/
+  test-results.json
+  smoke.spec.ts (optional copy only if generated specifically for the task)
+01-<criterion-slug>.png
+02-<criterion-slug>.png
+acceptance-summary.md
+```
+
+## Suggested verification flow
+
+### 1. Start the app
+
+Use the repository's normal local startup flow.
+
+Examples:
+
+```bash
+npm run dev
+```
+
+If frontend and backend run separately, ensure both are reachable before continuing.
+
+### 2. Use deterministic test data
+
+When a spec depends on one concrete record, prefer a stable URL or fixture.
+
+Examples:
+- a known `gameId`
+- a seeded local DB row
+- a fixture JSON file already captured in `.agent-workflow/specs/assets/<spec-slug>/`
+
+If stable data is not available, document the chosen runtime example inside `acceptance-summary.md`.
+
+### 3. Run Playwright checks
+
+At minimum, each UI-oriented acceptance run should:
+
+1. open the page or flow
+2. wait for the page heading or primary container
+3. assert the key labels/tabs/sections from the spec
+4. click through the primary interactions
+5. save screenshots after each meaningful state
+
+### 4. Save browser evidence
+
+Recommended screenshots for UI tasks:
+
+- top section / hero / summary state
+- each important tab
+- result state after interaction
+- any empty / fallback state explicitly required by the spec
+
+If a criterion spans multiple states, capture multiple screenshots.
+
+### 5. Write the acceptance summary
+
+For every acceptance criterion, record:
+
+- criterion text
+- classification (`ui`, `api`, `config`)
+- code status (`implemented` / `not implemented`)
+- automated verification (`passed` / `failed` / `not run`)
+- human verification (`pending` unless already performed)
+- evidence path(s)
+- notes / blockers
+
+## Screenshot naming
+
+Use ordered names tied to criterion order.
+
+Examples:
+
+```text
+01-route-navigation.png
+02-top-section.png
+03-team-stats-tab.png
+04-home-team-tab.png
+05-away-team-tab.png
+```
+
+If one criterion has multiple screenshots, suffix them:
+
+```text
+03-team-stats-tab-a.png
+03-team-stats-tab-b.png
+```
+
+## What good proof looks like
+
+Good:
+- “Playwright navigated from `/games` to `/games/123`, URL changed, page heading rendered, screenshot saved at `01-route-navigation.png`.”
+
+Bad:
+- “`onRowClick` was added in `Games.tsx`.”
+
+The second statement is implementation evidence, not acceptance evidence.
+
+## Suggested Playwright assertions
+
+Prefer assertions against user-visible UI:
+
+- heading text
+- table/tab labels
+- score line
+- player names
+- stat labels
+- empty-state text
+- navigation URL
+
+Avoid relying only on internal selectors when visible text is available.
+
+## When screenshots are enough
+
+For simple static UI changes, screenshots plus a few assertions are enough.
+
+## When video is worth adding
+
+Use video or a trace when:
+- multiple interactions are required
+- animation/state transitions matter
+- the bug is intermittent
+- reviewer context would benefit from replay
+
+## Failure handling
+
+If automated browser verification fails:
+
+1. save the failure screenshot
+2. record the actual error in `acceptance-summary.md`
+3. do not mark the criterion as passed
+4. do not open the MR until resolved or explicitly marked as blocked
+
+## Reviewer-friendly rule
+
+The reviewer should be able to glance at the artifact folder and understand whether the feature likely works **without pulling the branch first**.

package/templates/.agent-workflow/specs/README.md

@@ -0,0 +1,46 @@
+# Specs
+
+This folder contains feature specifications that drive implementation. Each `.md` file (except `_template.md`) describes one feature to be built.
+
+## Source of Truth
+
+Read `../README.md` first for the full workflow used by both Users and Agents.
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `open` | Ready for planning and implementation |
+| `done` | Already implemented and documented |
+
+## Verification Values
+
+| Verification | Meaning |
+|-------------|---------|
+| `true` | Use standard workflow checkpoints (plan approval and implementation approval). |
+| `false` | Skip verification checkpoints; agent creates plan, implements immediately, writes/updates docs, and marks spec done without waiting for approvals. |
+
+Example frontmatter:
+
+```yaml
+---
+status: open
+verification: true
+---
+```
+
+Backward compatibility: if `verification` is missing, treat it as `true`.
+
+## File Conventions
+
+- `_template.md` is a template, not a real feature.
+- All other `.md` files are specs (including historical specs).
+- Keep supporting assets in `./docs/` when useful for implementation context.
+
+## For AI Agents
+
+1. Read `../README.md` first.
+2. Find specs with `status: open`.
+3. Skip specs with `status: done`.
+4. Read `verification` in spec frontmatter (`true`/`false`, default to `true` when missing).
+5. Create plan files in `../plans/` and follow the full workflow.

package/templates/.agent-workflow/specs/_template.md

@@ -0,0 +1,60 @@
+---
+# status: draft (authoring) | open (ready for implementation) | done (finished)
+status: open
+# verification: true = plan/impl approval checkpoints; false = autonomous after plan
+verification: true
+# acceptance_proof: true = agent captures video/screenshots/curl output and posts to Slack before MR
+#                   false = skip capture (use only for pure config/infra specs with no visual or API surface)
+acceptance_proof: true
+---
+
+### Title
+
+Brief, user-impacting title.
+
+### Epic Context (Optional)
+
+*Include this section only if this feature is part of an epic*
+
+- Epic Name: [Name of the epic]
+- Epic README: [Link to epic README]
+- Feature Position: [Position in epic, e.g., "Feature 1 of 3"]
+
+### Summary
+
+One paragraph describing the problem and desired outcome.
+
+### Goals
+
+- What success looks like.
+
+### Non-Goals
+
+- Out-of-scope items.
+
+### Requirements
+
+- Functional requirements
+- Data and state changes
+- Permissions
+
+### UX / UI
+
+- Links to designs, screenshots, or sketches.
+
+### API / Data Contracts
+
+- Endpoints, payloads, GraphQL queries, or types.
+
+### Acceptance Criteria
+
+- [ ] Testable checklist items
+
+### Rollout / Risks
+
+- Migration, flags, monitoring, fallback.
+
+### References
+
+- Links to related specs, tickets, docs.
+

package/templates/.agent-workflow/specs/assets/README.md

@@ -0,0 +1,15 @@
+# Spec assets
+
+Store spec-specific supporting files here.
+
+## Structure
+- `.agent-workflow/specs/assets/<spec-slug>/...`
+
+## Examples
+- API response examples
+- screenshots from Notion or design tools
+- CSV samples
+- referenced markdown notes
+- diagrams
+
+Specs should reference these assets instead of keeping large payloads inline.

package/templates/.claude/rules/agentic-workflow.md

@@ -0,0 +1,138 @@
+# Claude operating rules for agentic workflow for this repository
+
+You are operating inside a spec-driven delivery workflow with GitLab merge-request handoff.
+Follow these rules in every session.
+
+## Read order at session start
+1. Read `.agent-workflow/README.md`
+2. Read `.agent-workflow/codebase.md` if it exists
+3. Read the target spec and any linked feature doc before planning or implementation
+4. Read relevant existing code (inside the appropriate submodule) before proposing structural changes
+
+## Source of truth
+- The spec is the source of truth for scope.
+- Acceptance Criteria define done.
+- Existing codebase conventions beat generic preferences.
+- Keep changes minimal unless the spec explicitly asks for broader refactoring.
+
+## Workflow states
+- `draft` = not ready for implementation
+- `open` = ready for planning and implementation
+- `done` = implementation, verification, docs, and handoff are complete
+
+Never implement a spec while it is `draft`.
+
+## Branch and worktree model
+- Spec preparation sessions use branch pattern `agent/spec/<slug>`.
+- Planning + implementation sessions use branch pattern `agent/task/<slug>`.
+- Worktrees live under `~/agent-runs/<repo>/worktrees/`.
+- Work only inside the current assigned worktree.
+- Never mix spec work and task work on the same branch.
+- Always branch from the repository default branch detected from GitLab remote state.
+
+## Required workflow
+### A. Prepare spec
+When asked to prepare a spec:
+- Create or update a file under `.agent-workflow/specs/`
+- Default status to `draft`
+- Default `verification: true` unless user explicitly says otherwise
+- Default `acceptance_proof: true` unless user explicitly says otherwise
+- Collect supporting assets into `.agent-workflow/specs/assets/<spec-slug>/`
+- Prefer assets over embedding large JSON, CSV, or screenshots inline
+- When spec is ready, commit the changes, push the current branch `agent/spec/<slug>`, and open or update a GitLab MR (always, unless the user explicitly says to skip GitLab flow)
+
+### B. Plan implementation
+When asked to implement a spec:
+- Confirm spec status is `open`
+- Create or update a plan in `.agent-workflow/plans/`
+- Validate impacted tables, files, APIs, and migrations against the actual codebase and schema before finalizing the plan
+- If `verification: true`, stop after drafting the plan and wait for approval
+- Commit and push the plan on the current `agent/task/<slug>` branch before waiting for approval (always, unless the user explicitly says to skip GitLab flow)
+
+### C. Implement
+After plan approval:
+- Work only on the approved scope
+- Keep changes aligned with existing project patterns
+- Add migrations or schema updates whenever persistent data structures change
+- Update the plan if implementation changes materially
+- Push the task branch as meaningful checkpoints are reached when requested
+
+### D. Verify and handoff
+Before marking work complete:
+- Execute or describe verification steps per acceptance criterion
+- Save evidence in `.agent-workflow/artifacts/<spec-slug>/`
+- Update or create the most relevant feature doc in `.agent-workflow/docs/`
+- Produce a concise MR summary
+- Push the branch and open or update the GitLab MR
+- Only then set the spec status to `done`
+
+## GitLab workflow rules
+- Prefer repository scripts under `scripts/agent/` for worktree, push, and MR actions.
+- Use `scripts/agent/git-detect-default-branch.sh` to resolve the target base branch.
+- Use `scripts/agent/git-push-branch.sh` before opening or updating an MR.
+- Use `scripts/agent/git-open-mr.sh` to create a new MR.
+- Use `scripts/agent/git-update-mr.sh` to refresh an existing MR description when continuing work on the same branch.
+- Never force-push.
+- Never open an MR against the wrong target branch.
+
+## Assets convention
+Store spec assets here:
+- `.agent-workflow/specs/assets/<spec-slug>/`
+
+Types of assets:
+- API examples (`.json`)
+- screenshots (`.png`, `.jpg`, `.webp`)
+- CSV samples
+- referenced markdown notes
+- diagrams
+
+If a Notion page links to another page, database item, table, image, or attachment relevant to implementation, retrieve it and store a local asset copy when practical.
+
+## Inconsistency handling
+If you discover a mismatch between:
+- acceptance criteria and real data,
+- spec text and existing schema,
+- plan assumptions and code reality,
+
+then do not silently continue.
+
+You must:
+1. stop,
+2. explain the inconsistency clearly,
+3. propose the smallest correction,
+4. wait for approval if the inconsistency changes expected behavior, counts, schema, or outputs.
+
+## Guardrails
+- Do not expand scope beyond the spec.
+- Do not move files to new locations unless required.
+- Do not create duplicate docs if an existing feature doc should be updated.
+- Do not invent migrations, fields, or endpoints without checking the actual code.
+- Do not claim verification that was not actually performed.
+- For UI tasks, prefer Playwright-first browser verification and screenshots over code-only assertions.
+- Do not commit unrelated files.
+- Ignore `.DS_Store` and `__MACOSX` artifacts if present in local archives.
+
+## Output expectations
+Every meaningful handoff should mention:
+- spec path
+- plan path
+- assets path if used
+- doc path updated
+- verification status
+- current branch
+- MR status or URL
+- blockers or assumptions
+
+## Preferred structure and naming
+- Specs: `.agent-workflow/specs/<date>_<slug>.md`
+- Plans: `.agent-workflow/plans/<spec-filename-without-ext>_plan.md`
+- Assets: `.agent-workflow/specs/assets/<spec-filename-without-ext>/`
+- Artifacts: `.agent-workflow/artifacts/<spec-filename-without-ext>/`
+
+## Practical prompting behavior
+When the user invokes `/prepare-spec`, `/implement-spec`, `/acceptance-proof`, or `/create-mr-summary` (or says "Use X skill"), follow that skill strictly.
+
+For acceptance proof on UI tasks, also read `.agent-workflow/playwright-acceptance.md`.
+
+## Meta-repo rule
+This is the project's meta repository. Specs, plans, docs, and artifacts live here. Application code changes go inside submodule directories (`backend/`, `web/`, `mobile/`). Each affected submodule gets its own MR in its own GitLab project. Never commit application code directly to the meta repo.

package/templates/.claude/settings.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Edit",
+      "Write",
+      "Read",
+      "Glob",
+      "Grep",
+      "NotebookEdit",
+      "WebFetch",
+      "WebSearch",
+      "Bash(find:*)",
+      "Bash(ls:*)",
+      "Bash(pwd:*)",
+      "Bash(cat:*)",
+      "Bash(sed:*)",
+      "Bash(grep:*)",
+      "Bash(rg:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(sort:*)",
+      "Bash(uniq:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(touch:*)",
+      "Bash(chmod:*)",
+      "Bash(date:*)",
+      "Bash(jq:*)",
+      "Bash(npm run *)",
+      "Bash(npm test *)",
+      "Bash(npm install *)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git add:*)",
+      "Bash(git restore:*)",
+      "Bash(git checkout:*)",
+      "Bash(git switch:*)",
+      "Bash(git branch:*)",
+      "Bash(git fetch:*)",
+      "Bash(git pull:*)",
+      "Bash(git worktree:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git remote:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(glab:*)",
+      "Bash(curl:*)",
+      "Bash(python3:*)",
+      "Bash(claude mcp:*)",
+      "Bash(node:*)",
+      "Bash(timeout:*)",
+      "Bash(pkill:*)",
+      "Bash(sleep:*)",
+      "Bash(echo:*)"
+    ],
+    "deny": [
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git reset --hard*)",
+      "Bash(rm -rf /:*)",
+      "Bash(sudo:*)",
+      "Bash(curl *prod*:*)",
+      "Bash(curl *production*:*)",
+
+      "Read(./**/secrets/**)",
+      "Bash(rm -rf /)",
+      "Bash(sudo *)"
+    ]
+  },
+  "env": {
+    "AGENT_WORKFLOW_ROOT": ".agent-workflow"
+  }
+}

package/templates/.claude/skills/acceptance-proof/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: acceptance-proof
+description: Produce explicit acceptance verification evidence for every acceptance criterion in a spec and store the evidence under the standard artifact path.
+---
+
+Use this skill after implementation or when the user explicitly asks for acceptance verification.
+
+## Goal
+Create a clear artifact trail showing whether each acceptance criterion passed or failed.
+
+## Inputs
+- target spec path
+- optional implementation context
+- optional commands or endpoints to exercise
+
+## Output location
+Store artifacts in:
+- `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/`
+
+## Required process
+1. Read the acceptance criteria from the spec.
+2. Number them in order.
+3. For each criterion, capture:
+   - criterion text
+   - method used to verify it
+   - classification (`ui`, `api`, `config`)
+   - code status (`implemented` / `not implemented`)
+   - human verification (`pending` unless already checked)
+   - command, request, screenshot, or file used as evidence
+   - observed result
+   - automated verification (`passed` / `failed` / `not run`)
+4. Save one artifact file per criterion when useful, plus a short summary index.
+
+## Artifact naming
+Examples:
+- `01-sync-endpoint.txt`
+- `02-fetch-endpoint.txt`
+- `03-route-navigation.png`
+- `04-team-stats-tab.png`
+- `05-game-summary-response.txt`
+- `acceptance-summary.md`
+
+## Rules
+- Do not claim a pass without evidence.
+- If a criterion cannot be verified, state why.
+- If the live result contradicts the spec, flag it as an inconsistency and recommend a spec correction instead of hiding the issue.
+- Keep artifacts concise and easy to review in a PR.
+- Distinguish clearly between `implemented`, `verified automatically`, and `human QA pending`.
+
+## Final handoff
+Return:
+- artifact directory path
+- per-criterion pass/fail summary
+- inconsistencies found
+- note whether UI criteria were verified in-browser or only inspected statically
+
+## UI tasks
+For frontend/UI tasks, acceptance proof is incomplete unless runtime browser evidence is included. Prefer Playwright for:
+- route navigation
+- tab or modal behavior
+- visible text and layout checks
+- screenshots attached to the artifact folder
+
+When UI proof is produced, report each criterion using:
+- Code status
+- Automated verification
+- Human QA
+- Evidence

package/templates/.claude/skills/create-mr-summary/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: create-mr-summary
+description: Produce a concise PR/MR summary grounded in the spec, plan, implementation, docs update, and acceptance evidence.
+---
+
+Use this skill when work is complete and a merge request description or handoff summary is needed.
+
+## Required inputs
+- spec path
+- plan path
+- relevant changed files
+- docs path
+- artifact path
+
+## Output format
+Generate a markdown summary with these sections:
+- Title
+- What changed
+- Why
+- Files/areas touched
+- Verification
+- Docs updated
+- Follow-ups / risks
+
+## Rules
+- Base the summary on actual completed work, not intention.
+- Mention any approved deviation from the original spec.
+- Reference acceptance artifacts explicitly.
+- Keep it easy for reviewer scanning.