@codebehind/agent-workflow 1.0.0

package/templates/.claude/skills/implement-spec/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: implement-spec
+description: Read an open spec, produce a verified plan, stop for approval when required, implement the approved scope, update docs and artifacts, and publish progress through GitLab on a task branch.
+---
+
+Use this skill when the user points to a spec file for implementation.
+
+## Preconditions
+- Target spec exists
+- Spec status is `open`
+
+If the spec is still `draft`, stop and explain that it must be reviewed and moved to `open` first.
+
+## Required sequence
+### 1. Read context
+Read:
+- target spec
+- `.agent-workflow/codebase.md`
+- relevant existing feature docs
+- relevant code, schema, migrations, controllers, and tests
+
+### 2. Draft plan
+Create or update `.agent-workflow/plans/<spec-filename-without-ext>_plan.md`
+
+The plan must include:
+- goal summary
+- impacted files/modules
+- schema/migration impact
+- endpoint/query impact
+- implementation steps
+- verification approach by acceptance criterion
+- risks / open questions
+
+### 3. Validate before proceeding
+Before implementation, validate:
+- referenced tables actually exist
+- chosen data sources are correct
+- migrations are included when persistent schema changes are required
+- endpoints/queries reflect real project patterns
+- acceptance criteria are internally consistent with real data when verifiable
+
+### 4. Handle inconsistencies
+If you detect mismatch between spec and reality, do not silently correct it.
+Stop and report:
+- what is inconsistent
+- what you checked
+- the smallest proposed correction
+- whether approval is required before continuing
+
+### 5. Approval gate
+If `verification: true`, stop after the plan and wait for explicit approval.
+Do not implement before approval.
+
+If running on an `agent/task/<slug>` branch:
+- commit the plan,
+- push the branch with `scripts/agent/git-push-branch.sh`,
+- open or update the MR so the user can review the plan there,
+- then wait.
+
+### 6. Implement
+After approval:
+- modify only required files
+- keep scope tight
+- follow existing architecture and naming
+- update the plan if implementation changes materially
+- commit meaningful milestones when helpful
+
+### 7. Verify
+For each acceptance criterion:
+- run or describe concrete verification steps (for the current project, run inside the relevant submodule directory)
+- save proof into `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/`
+- note pass/fail clearly per `.agent-workflow/acceptance-verification.md`
+
+### 8. Update docs
+Update the most relevant existing doc in `.agent-workflow/docs/` if one already covers the feature area.
+Only create a new doc if no existing doc is the right place.
+
+### 9. GitLab handoff
+1. Stage only the relevant meta-repo files (spec, plan, docs, artifacts — not submodule code).
+2. Commit current changes.
+3. Push with `scripts/agent/git-push-branch.sh`.
+4. Generate MR body content using `scripts/agent/mr-template.sh task <spec-path> <plan-path> <doc-path-or-dash> <artifacts-path-or-dash>`.
+5. Open or update the MR using the scripts in `scripts/agent/`.
+6. If submodule code was changed, open separate MRs in the affected submodule GitLab projects and reference them in the meta repo MR description.
+
+### 10. Final handoff
+Provide:
+- files changed
+- plan path
+- artifacts path
+- docs path
+- unresolved issues
+- MR summary draft
+- MR URL if created or updated
+
+### 11. Completion
+Set spec status to `done` only after implementation, verification, artifacts, docs, and GitLab handoff are complete.

package/templates/.claude/skills/prepare-spec/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: prepare-spec
+description: Turn a Notion task or free-form request into a repository spec file, gather supporting assets, commit the result on a spec branch, and open or update a GitLab MR.
+---
+
+Use this skill when the user wants a new spec created or an existing draft refined.
+
+## Objective
+Produce a clean implementation-ready spec in `.agent-workflow/specs/`, gather relevant supporting files in `.agent-workflow/specs/assets/<spec-slug>/`, and hand the result off through GitLab when the current session is running in the local GitLab workflow.
+
+## Inputs
+Possible inputs:
+- pasted Notion task content
+- Notion page or subpage content available through connectors
+- screenshots or JSON examples
+- short free-form feature request
+
+## Required behavior
+1. Read `.agent-workflow/specs/_template.md` if present.
+2. Determine the spec filename using the convention `<YYYYMMDD>_<slug>.md` when a date is known; otherwise preserve project conventions.
+3. Create the asset directory `.agent-workflow/specs/assets/<spec-slug>/` if supporting assets exist or should exist.
+4. If the source page references linked pages, child pages, attachments, tables, images, code blocks, or JSON examples relevant to delivery:
+   - inspect them,
+   - extract what matters,
+   - save local copies into the spec asset directory when practical,
+   - reference those assets from the spec.
+5. Default frontmatter:
+   - `status: draft`
+   - `verification: true`
+   - `acceptance_proof: true`
+6. Keep the scope concrete and implementation-oriented.
+7. Do not mark the spec `open` yourself unless the user explicitly asks you to.
+
+## Spec sections
+Include these sections unless the repo template already defines them:
+- Title
+- Summary
+- Goals
+- Non-Goals
+- Requirements
+- UX / UI
+- API / Data Contracts
+- Acceptance Criteria
+- Rollout / Risks
+- References
+- Assets
+
+## Quality bar
+- Acceptance criteria must be testable.
+- Counts, IDs, endpoints, and expected results must be internally consistent.
+- If counts or expected outputs look suspicious, call them out in a `Spec review notes` subsection at the bottom.
+- Prefer linking large payload examples as assets instead of embedding them inline.
+
+## Asset rules
+Store assets in:
+- `.agent-workflow/specs/assets/<spec-slug>/`
+
+Use filenames that reveal purpose, for example:
+- `rapidapi-game-summary-response.json`
+- `ui-reference-mobile.png`
+- `db-shape-notes.md`
+
+## GitLab handoff behavior
+1. Stage only the relevant spec, asset, and doc changes (no submodule code).
+2. Create a focused commit.
+3. Push the current branch with `scripts/agent/git-push-branch.sh`.
+4. Generate MR body content using `scripts/agent/mr-template.sh spec <spec-path> - - -`.
+5. Open or update the MR using the scripts in `scripts/agent/`.
+
+## Final handoff
+Return:
+- created or updated spec path
+- created asset paths
+- missing assumptions or ambiguities
+- recommendation on whether the spec is ready to move from `draft` to `open`
+- commit status
+- MR URL if created or updated

package/templates/AGENTS.md

@@ -0,0 +1,43 @@
+# Agent Onboarding
+
+## Workflow Process
+
+This repository uses a structured feature delivery workflow.
+
+**CRITICAL**: Before starting any work, read `.agent-workflow/README.md` to understand the complete workflow.
+
+## Quick Start
+
+1. Read `.agent-workflow/README.md` (workflow process — **Phase A** spec authorship vs **Phase B** delivery).
+2. Read `.agent-workflow/codebase.md` (codebase snapshot — do NOT rescan unless explicitly asked).
+3. Determine the task:
+   - **Prepare a spec** (user pasted Notion URL, asked for chat-assisted drafting, or asked to convert Notion → spec): follow **Phase A**; write `.agent-workflow/specs/*.md` with `status: draft` unless the user says otherwise; use `.agent-workflow/notion-spec-mapping.md` for Notion.
+   - **Implement a feature**: only specs with **`status: open`**; check `.agent-workflow/specs/` for those.
+4. For implementation, read `verification` in each open spec (`true|false`, default to `true` when missing).
+5. Follow the workflow: **open** spec → plan → implement → document → mark spec `done`.
+
+## Meta-repo rule
+
+This is the **Mjaumatish 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.
+- When running acceptance proof (UI, API), navigate inside the relevant submodule to start the app and capture evidence. Save artifacts back here under `.agent-workflow/artifacts/`.
+- Reference submodule MR URLs in the meta repo MR description.
+
+## Key Points
+
+- Specs use **`draft`** while authoring; **`open`** means ready for implementation (Phase B).
+- Users promote **`draft` → `open`** after review, or ask the agent to do so.
+- **Implementation** only applies to **`status: open`** specs.
+- Users can set `verification: false` for autonomous execution without verification checkpoints in Phase B.
+- Agents create plans, implement, and document features per `.agent-workflow/README.md`.
+- With `verification: false`, agents proceed after plan creation, then finish docs and mark spec done without waiting for approval pauses.
+- All work follows the structured workflow in `.agent-workflow/`.
+
+## Acceptance proof reminder
+
+- For UI work, proof must be **runtime evidence**, not code references.
+- Prefer Playwright screenshots per acceptance criterion or per major UI state.
+- Distinguish clearly between `implemented`, `verified automatically`, and `human QA pending`.
+- Follow `.agent-workflow/acceptance-verification.md` and `.agent-workflow/playwright-acceptance.md`.
+- For this meta repo: run the app inside the relevant submodule directory; save artifacts here.

package/templates/agents-workflow-dev-process.md

@@ -0,0 +1,212 @@
+# Agents Workflow — Development Process
+
+This document describes how we use **Claude Code** with the `.agent-workflow/` convention in this repository: from writing a spec to opening a merge request and merging.
+
+---
+
+## Overview
+
+Work flows through two phases:
+
+| Phase | What happens | Skill |
+|-------|-------------|-------|
+| **A — Prepare spec** | Create or refine a spec file (`draft`) | `/prepare-spec` |
+| **B — Implement spec** | Plan → code → docs for an `open` spec | `/implement-spec` |
+
+Phases are kept in **separate Claude sessions** on **separate branches** to keep spec authoring and implementation cleanly isolated.
+
+---
+
+## Prerequisites
+
+- `git`
+- [`glab`](https://gitlab.com/gitlab-org/cli) (GitLab CLI) — authenticated via `glab auth login`
+- `jq`
+- Claude Code CLI (running locally)
+
+See `agents-workflow-env-setup.md` for initial setup.
+
+---
+
+## What is a spec?
+
+A **spec** is the authoritative description of what should be built and what "done" means. It lives in:
+
+```
+.agent-workflow/specs/{name}.md
+```
+
+Specs use **YAML frontmatter**:
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `status` | `draft` / `open` / `done` | `draft` = authoring; `open` = ready for Phase B; `done` = delivered |
+| `verification` | `true` / `false` | `true` = human checkpoints during Phase B; `false` = autonomous after plan |
+| `acceptance_proof` | `true` / `false` | `true` = runtime evidence required; `false` = text-only (config/infra only) |
+
+Use `_template.md` when creating specs by hand.
+
+---
+
+## Phase A — Prepare spec
+
+### Option 1: From a Notion page
+
+Start a **new Claude Code session** in the repo root worktree and say:
+
+```
+Use prepare-spec skill. Source: <notion-url>
+```
+
+The agent fetches the Notion page, maps content to the spec template, asks clarifying questions, then writes `.agent-workflow/specs/<date>_<slug>.md` with `status: draft`.
+
+### Option 2: From a description
+
+```
+Use prepare-spec skill.
+
+<short title and bullet-point description of the feature>
+```
+
+### Option 3: By hand
+
+Copy `.agent-workflow/specs/_template.md` to `.agent-workflow/specs/<name>.md`, fill it in, and set `status: draft` (or `open` if ready).
+
+### After spec prep
+
+1. Review the spec in the MR opened on branch `agent/spec/<slug>`.
+2. Edit if needed.
+3. Set `status: open` when ready for development (edit the file or ask the agent to flip it).
+4. Merge the spec MR into main.
+
+---
+
+## Phase B — Implement spec
+
+The spec must have `status: open` and be merged to main before starting Phase B.
+
+### Start a task session
+
+From the repo root:
+
+```bash
+scripts/agent/git-prepare-worktree.sh task <slug>
+```
+
+This creates a worktree at `~/agent-runs/mjaumatish-meta/worktrees/task-<slug>` on branch `agent/task/<slug>`.
+
+Open Claude Code in that worktree:
+
+```bash
+cd ~/agent-runs/mjaumatish-meta/worktrees/task-<slug>
+claude
+```
+
+Then instruct the agent:
+
+```
+Use implement-spec skill for .agent-workflow/specs/<spec-file>.md.
+Follow the local GitLab workflow. Create the plan first, push it, and stop for approval.
+```
+
+### What the agent does
+
+1. Reads the spec, codebase snapshot, and relevant existing docs.
+2. Creates `.agent-workflow/plans/<spec-name>_plan.md`.
+3. If `verification: true` (default): commits the plan, pushes, opens/updates an MR, and **waits for your approval**.
+4. After approval (or immediately if `verification: false`): implements the feature — code changes go into the relevant submodule(s) (`backend/`, `web/`, `mobile/`).
+5. Runs acceptance verification per the criteria in the spec.
+6. Writes/updates a feature doc in `.agent-workflow/docs/`.
+7. Opens or updates the MR with the full summary.
+8. Sets the spec to `status: done`.
+
+### Continue after plan approval
+
+Reply in the same Claude session:
+
+```
+Proceed with implementation.
+```
+
+Or start a fresh session in the same worktree and say:
+
+```
+Use implement-spec skill for .agent-workflow/specs/<spec-file>.md. Plan is approved, proceed with implementation.
+```
+
+---
+
+## Meta-repo specifics
+
+This is a **meta repository**. Specs, plans, docs, and artifacts all live here under `.agent-workflow/`. Application code changes, however, go inside the submodule directories.
+
+| What | Where it lives |
+|------|---------------|
+| Spec, plan, docs, artifacts | `.agent-workflow/` in this meta repo |
+| Backend code changes | `backend/` submodule → MR in mjaumatish-backend |
+| Web code changes | `web/` submodule → MR in mjaumatish-web |
+| Mobile code changes | `mobile/` submodule → MR in mjaumatish-mobile |
+| Acceptance proof (runtime) | Runs inside the relevant submodule; artifacts stored here |
+
+A cross-cutting spec (touching multiple repos) results in one plan here and separate MRs in each affected sub-repo.
+
+---
+
+## Verification: checkpoints or autonomous
+
+Controlled by the spec's `verification` field (default `true`):
+
+| Value | Behavior |
+|-------|----------|
+| `true` | Agent drafts a plan, commits it, opens an MR, and waits for your explicit approval before implementing. |
+| `false` | Agent proceeds autonomously after the plan — implements, verifies, docs, MR, done. |
+
+Use `false` for low-risk, well-defined tasks. Use `true` (default) when you want to review the plan before code is written.
+
+---
+
+## Acceptance proof
+
+After implementation, the agent verifies each acceptance criterion and saves evidence under:
+
+```
+.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/
+```
+
+For UI and API criteria, this means runtime evidence (screenshots, curl output) — not just "the code was added." See `.agent-workflow/acceptance-verification.md` for the full protocol.
+
+---
+
+## GitLab MR flow
+
+Scripts under `scripts/agent/` handle the GitLab integration:
+
+| Script | Purpose |
+|--------|---------|
+| `git-prepare-worktree.sh` | Create a worktree + branch for spec or task work |
+| `git-push-branch.sh` | Push the current branch to origin |
+| `git-open-mr.sh` | Open a new MR (or update existing) via `glab` |
+| `git-detect-default-branch.sh` | Resolve the target base branch from origin |
+| `git-update-mr.sh` | Update an existing MR description |
+| `cleanup-worktree.sh` | Remove a worktree after work is merged |
+
+The agent uses these automatically when instructed to follow the local GitLab workflow.
+
+---
+
+## Quick reference
+
+| Concept | Rule |
+|---------|------|
+| Spec location | `.agent-workflow/specs/` in meta repo only |
+| Spec status | `draft` → author; `open` → implement; `done` → finished |
+| Phase A session | Any worktree; use `/prepare-spec` skill |
+| Phase B session | `~/agent-runs/mjaumatish-meta/worktrees/task-<slug>` |
+| Branch — spec | `agent/spec/<slug>` |
+| Branch — task | `agent/task/<slug>` |
+| Code changes | Inside submodule dirs (`backend/`, `web/`, `mobile/`) |
+| Verification | `true` = plan approval checkpoint (default); `false` = autonomous |
+| Acceptance proof | `true` = runtime evidence required (default); `false` = config/infra only |
+| Docs | `.agent-workflow/docs/` + add spec under **Covered Specs** |
+| Artifacts | `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/` |
+| Done | Acceptance proof attached to MR → review → **merge** |

package/templates/agents-workflow-env-setup.md

@@ -0,0 +1,136 @@
+# Agent Workflow — Environment Setup
+
+One-time setup for working with Claude Code and the `.agent-workflow/` convention in this repository.
+
+---
+
+## Prerequisites
+
+Install these tools before starting:
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| `git` | Version control | System package manager |
+| [`glab`](https://gitlab.com/gitlab-org/cli) | GitLab CLI (MR management) | `brew install glab` |
+| `jq` | JSON processing (used by agent scripts) | `brew install jq` |
+| `node` 20+ | Used by some agent scripts | `brew install node` |
+| Claude Code CLI | AI agent | See [claude.ai/code](https://claude.ai/code) |
+
+---
+
+## 1. Clone with submodules
+
+```bash
+git clone --recurse-submodules https://gitlab.com/codebehind/mjaumatish/mjaumatish-meta.git
+cd mjaumatish-meta
+```
+
+Or if already cloned without submodules:
+
+```bash
+./scripts/bootstrap.sh
+```
+
+---
+
+## 2. Authenticate with GitLab
+
+```bash
+glab auth login
+```
+
+Follow the prompts. Choose HTTPS and paste a GitLab personal access token with `api` scope.
+
+Verify:
+
+```bash
+glab auth status
+```
+
+---
+
+## 3. Make agent scripts executable
+
+```bash
+chmod +x scripts/agent/*.sh
+```
+
+---
+
+## 4. Create the worktree root directory
+
+Agent worktrees live outside the main repo clone:
+
+```bash
+mkdir -p ~/agent-runs/mjaumatish-meta/worktrees
+```
+
+---
+
+## 5. Verify the default branch
+
+The agent scripts auto-detect the default branch from origin. You can check it manually:
+
+```bash
+scripts/agent/git-detect-default-branch.sh origin
+```
+
+Should return `main`.
+
+---
+
+## 6. Open Claude Code in the repo root
+
+```bash
+cd mjaumatish-meta
+claude
+```
+
+Claude Code will read `CLAUDE.md` and `.claude/rules/agentic-workflow.md` automatically at session start.
+
+---
+
+## Running a spec session (Phase A)
+
+From the repo root (no worktree needed for spec prep):
+
+```bash
+claude
+# then in the session:
+# Use prepare-spec skill. <description or Notion URL>
+```
+
+The agent will create a branch `agent/spec/<slug>`, commit the spec, and open a GitLab MR.
+
+---
+
+## Running a task session (Phase B)
+
+```bash
+# 1. Prepare a worktree for the task
+scripts/agent/git-prepare-worktree.sh task <slug>
+
+# 2. Open Claude Code in the worktree
+cd ~/agent-runs/mjaumatish-meta/worktrees/task-<slug>
+claude
+
+# 3. Instruct the agent
+# Use implement-spec skill for .agent-workflow/specs/<spec-file>.md.
+# Follow the local GitLab workflow. Create the plan, push it, stop for approval.
+```
+
+---
+
+## Cleanup after a branch is merged
+
+```bash
+scripts/agent/cleanup-worktree.sh <slug>
+```
+
+---
+
+## Keeping submodules up to date
+
+```bash
+./scripts/update-submodules.sh
+```

package/templates/scripts/agent/LOCAL_GITLAB_WORKFLOW.md

@@ -0,0 +1,83 @@
+# Local GitLab + Worktree Workflow
+
+This repository supports a local Claude Code workflow with Git worktrees and GitLab merge requests.
+
+## Prerequisites
+- `git`
+- `glab`
+- `jq`
+- authenticated `glab auth login`
+- Claude Code running locally with repo instructions enabled
+
+## Branch conventions
+- Spec prep: `agent/spec/<slug>`
+- Task work (plan + implementation): `agent/task/<slug>`
+
+## Worktree root
+- `~/agent-runs/<repo>/worktrees/`
+
+## 1. Start a spec run
+From the main repo root:
+
+```bash
+scripts/agent/git-prepare-worktree.sh spec <slug>
+```
+
+Then open Claude in the created worktree and instruct it to use the `prepare-spec` skill.
+
+Expected result:
+- draft spec created or updated
+- assets stored under `.agent-workflow/specs/assets/<spec-slug>/`
+- commit created
+- branch pushed
+- MR opened automatically via `glab`
+
+## 2. Review and merge spec MR
+- review the MR
+- request changes if needed
+- once ready, mark the spec `open`
+- merge the MR
+
+## 3. Start a task run
+From the main repo root:
+
+```bash
+scripts/agent/git-prepare-worktree.sh task <slug>
+```
+
+Then open Claude in the created worktree and instruct it to use the `implement-spec` skill.
+
+Expected result before approval:
+- plan created or updated
+- plan committed on `agent/task/<slug>`
+- branch pushed
+- MR opened or updated for plan review
+- agent stops when `verification: true`
+
+After approval:
+- implementation proceeds on same branch
+- artifacts are created
+- docs are updated
+- MR is updated for final review
+
+## Suggested prompts
+### Spec agent
+```text
+Use prepare-spec skill for this Notion task. Follow the local GitLab workflow in this repo. When the spec is ready, commit, push, and open or update the merge request.
+```
+
+### Task agent
+```text
+Use implement-spec skill for .agent-workflow/specs/<spec-file>.md. Follow the local GitLab workflow in this repo. Create the plan first, push it, and stop for approval because verification=true.
+```
+
+### Continue after plan approval
+```text
+Proceed with implementation, verification artifacts, docs update, and merge request update.
+```
+
+## Notes
+- The target branch is always the repository default branch detected from origin.
+- Do not force-push.
+- Do not reuse a spec branch for task work.
+- Prefer one Claude session per branch/worktree.

package/templates/scripts/agent/cleanup-worktree.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <repo_root> <spec_slug> [--delete-branch]" >&2
+  exit 1
+fi
+
+REPO_ROOT="$1"
+SPEC_SLUG="$2"
+DELETE_BRANCH="${3:-}"
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+WORKTREE_PATH="$REPO_ROOT/.worktrees/$SPEC_SLUG"
+BRANCH_NAME="feature/agent/$SPEC_SLUG"
+
+cd "$REPO_ROOT"
+if [[ -d "$WORKTREE_PATH" ]]; then
+  git worktree remove "$WORKTREE_PATH" --force
+fi
+
+if [[ "$DELETE_BRANCH" == "--delete-branch" ]]; then
+  git branch -D "$BRANCH_NAME" 2>/dev/null || true
+fi