@codebehind/agent-workflow 1.1.4 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codebehind/agent-workflow",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Scaffold the agent-workflow spec-driven delivery framework into any repo",
   "type": "module",
   "bin": {

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

@@ -142,19 +142,21 @@ For non-trivial changes not described by a new feature spec:
 
 ---
 
-## Meta-repo specifics
+## Repo mode
 
-This is the project's meta repository. The `.agent-workflow/` directory exists **only here** — there are no per-submodule workflow directories.
+Check `AGENTS.md` for the declared repo mode.
+
+**Single-repo:** All code, specs, plans, docs, and artifacts live here. Commit and MR everything in this repo. One MR per task branch.
+
+**Meta-repo:** The `.agent-workflow/` directory exists only here — there are no per-submodule workflow directories.
 
 | Content | Location |
 |---------|---------|
 | Specs, plans, feature docs, artifacts | This repo under `.agent-workflow/` |
-| Backend application code | `backend/` submodule — commit and MR in project-backend |
-| Web application code | `web/` submodule — commit and MR in project-web |
-| Mobile application code | `mobile/` submodule — commit and MR in project-mobile |
+| Application code | `repos/<module>/` submodules — see `AGENTS.md` for the full list and their GitLab project URLs |
 
-When implementing a spec that touches application code:
-1. Navigate into the relevant submodule directory to make code changes.
+When implementing a spec that touches application code (meta-repo only):
+1. Navigate into the relevant `repos/<module>/` directory to make code changes.
 2. Open a separate MR in that submodule's GitLab project.
-3. The meta repo MR covers only spec, plan, docs, and artifacts.
-4. Reference the submodule MR(s) in the meta repo MR description.
+3. The meta-repo MR covers only spec, plan, docs, and artifacts.
+4. Reference the submodule MR(s) in the meta-repo MR description.

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

@@ -4,9 +4,12 @@ This document defines how agents **verify acceptance criteria and report proof**
 
 ---
 
-## Meta-repo note
+## Where to run acceptance proof
 
-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/`.
+Check `AGENTS.md` for the repo mode:
+
+- **Single-repo:** run the app from the repo root. Save artifacts under `.agent-workflow/artifacts/`.
+- **Meta-repo:** navigate into the relevant `repos/<module>/` directory to start the app and run proof. Save artifacts back here under `.agent-workflow/artifacts/`.
 
 ---
 

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

@@ -4,10 +4,11 @@ You are operating inside a spec-driven delivery workflow with GitLab merge-reque
 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
+1. Read `AGENTS.md` — determines repo mode (single-repo vs meta-repo) and project context
+2. Read `.agent-workflow/README.md`
+3. Read `.agent-workflow/codebase.md` if it exists
+4. Read the target spec and any linked feature doc before planning or implementation
+5. Read relevant existing code (in the appropriate directory) before proposing structural changes
 
 ## Source of truth
 - The spec is the source of truth for scope.
@@ -134,5 +135,9 @@ When the user invokes `/prepare-spec`, `/implement-spec`, `/acceptance-proof`, o
 
 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.
+## Repo mode rule
+Read `AGENTS.md` to determine the repo mode declared for this project.
+
+**Single-repo mode:** Application code, specs, plans, docs, and artifacts all live in this repository. Commit everything here. One MR per task branch covers all changes.
+
+**Meta-repo mode:** Specs, plans, docs, and artifacts live in this repository. Application code lives in `repos/<module>/` submodules as declared in `AGENTS.md`. Never commit application code directly to this repo. Each affected submodule gets its own MR in its own GitLab project. Reference all submodule MR URLs in the meta-repo MR description. For acceptance proof requiring a running app, navigate into the relevant `repos/<module>/` directory; save artifacts back here under `.agent-workflow/artifacts/`.

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

@@ -67,7 +67,7 @@ After approval:
 
 ### 7. Verify
 For each acceptance criterion:
-- run or describe concrete verification steps (for the current project, run inside the relevant submodule directory)
+- run or describe concrete verification steps — check `AGENTS.md`: single-repo → run from repo root; meta-repo → run inside the relevant `repos/<module>/` directory
 - save proof into `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/`
 - note pass/fail clearly per `.agent-workflow/acceptance-verification.md`
 
@@ -76,12 +76,22 @@ Update the most relevant existing doc in `.agent-workflow/docs/` if one already
 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).
+Check `AGENTS.md` for repo mode:
+
+**Single-repo:**
+1. Stage all changed files (code, spec, plan, docs, artifacts).
+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/`.
+
+**Meta-repo:**
+1. Stage only the files in this repo (spec, plan, docs, artifacts — not `repos/<module>/` 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.
+6. For each `repos/<module>/` that had code changes, open a separate MR in that submodule's GitLab project and reference its URL in the meta-repo MR description.
 
 ### 10. Final handoff
 Provide:

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

@@ -61,7 +61,7 @@ Use filenames that reveal purpose, for example:
 - `db-shape-notes.md`
 
 ## GitLab handoff behavior
-1. Stage only the relevant spec, asset, and doc changes (no submodule code).
+1. Stage only the relevant spec, asset, and doc changes.
 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> - - -`.

package/templates/AGENTS.md

@@ -6,6 +6,8 @@ This repository uses a structured feature delivery workflow.
 
 **CRITICAL**: Before starting any work, read `.agent-workflow/README.md` to understand the complete workflow.
 
+See `agents-workflow-dev-process.md` for both the **scripted workflow** (bash scripts, auto worktrees) and the **direct workflow** (manual branch + `claude` in the repo root — no worktrees required).
+
 ## Quick Start
 
 1. Read `.agent-workflow/README.md` (workflow process — **Phase A** spec authorship vs **Phase B** delivery).
@@ -16,13 +18,23 @@ This repository uses a structured feature delivery workflow.
 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
+## Repo Mode
+
+**Mode:** single-repo
+<!-- Change to "meta-repo" if this repo holds only specs/plans/docs and application code lives in repos/<module>/ submodules. -->
+
+<!-- If meta-repo, fill in the submodule table below and delete this comment block:
+| Directory        | GitLab project URL |
+|------------------|--------------------|
+| repos/backend/   | gitlab.com/org/project-backend |
+| repos/web/       | gitlab.com/org/project-web |
+-->
 
-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.
+**Single-repo:** All application code, specs, plans, docs, and artifacts live in this repository. Commit everything here. One MR per task branch.
 
-- 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.
+<!-- If meta-repo, replace the line above with:
+**Meta-repo:** Specs, plans, docs, and artifacts live here. Application code lives in `repos/<module>/` submodules (see table above). Never commit application code directly to this repo. Each affected submodule gets its own MR in its own GitLab project. Reference submodule MR URLs in the meta-repo MR description. When running acceptance proof (UI, API), navigate into the relevant `repos/<module>/` directory to start the app and capture evidence; save artifacts back here under `.agent-workflow/artifacts/`.
+-->
 
 ## Key Points
 
@@ -40,4 +52,4 @@ This is the **Mjaumatish meta repository**. Specs, plans, docs, and artifacts li
 - 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.
+- **Single-repo:** run the app from the repo root. **Meta-repo:** navigate into the relevant `repos/<module>/` directory to start the app; save artifacts here under `.agent-workflow/artifacts/`.

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

@@ -15,6 +15,15 @@ Work flows through two phases:
 
 Phases are kept in **separate Claude sessions** on **separate branches** to keep spec authoring and implementation cleanly isolated.
 
+There are two ways to run each phase:
+
+| Mode | How |
+|------|-----|
+| **Scripted (worktrees)** | Run the bash scripts — they create a git worktree, branch, and start Claude automatically |
+| **Direct (no worktrees)** | Create the branch manually, open Claude in the repo root, invoke the skill yourself |
+
+Both modes are fully supported. Choose based on your preference.
+
 ---
 
 ## Prerequisites
@@ -50,31 +59,51 @@ Use `_template.md` when creating specs by hand.
 
 ## Phase A — Prepare spec
 
-### Option 1: From a Notion page
+### Option 1: Scripted (worktrees) — from a Notion page
 
-In the repo root worktree start following command (this will create new git worktree, branch and start new claude session with /prepare-spec skill):
+From the repo root, run:
 
 ```bash
-scripts/agent/prepare-spec <slug> <notion-link>
+scripts/agent/prepare-spec.sh <slug> <notion-link>
 ```
 
-This command: 
+This script:
 - creates a worktree at `~/agent-runs/{PROJECT_NAME}/worktrees/spec-<slug>` on branch `agent/spec/<slug>`
-- starts Claude session in `~/agent-runs/{PROJECT_NAME}/worktrees/spec-<slug>` on branch `agent/spec/<slug>`
-- iniate `/prepare-spec` skill from given <notion-link>
+- starts a Claude session inside that worktree
+- invokes `/prepare-spec` with the given Notion link
 
 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
+Add `--interactive` to follow along in the same session and skip the automatic GitLab MR:
 
-TBD
+```bash
+scripts/agent/prepare-spec.sh --interactive <slug> <notion-link>
 ```
-# Still in progress...
+
+Claude launches interactively with the first message pre-filled. The worktree and branch are still created — but nothing is pushed or opened in GitLab unless you do it manually.
+
+### Option 2: Direct (no worktrees) — from a Notion page or description
+
+Skip the script and run everything yourself:
+
+```bash
+# 1. Create and switch to a spec branch
+git checkout -b agent/spec/<slug>
+
+# 2. Open Claude in the repo root
+claude
+
+# 3. Inside Claude, invoke the skill
+/prepare-spec <notion-link>
+# or for a free-form description:
+# "Use prepare-spec skill, here is the feature: ..."
 ```
 
+The agent will write the spec, commit it, and open a GitLab MR on the current branch — no worktree needed.
+
 ### 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).
+Copy `.agent-workflow/specs/_template.md` to `.agent-workflow/specs/<name>.md`, fill it in, and set `status: draft` (or `open` if ready). Then commit and push the branch yourself.
 
 ### After spec prep
 
@@ -89,26 +118,45 @@ Copy `.agent-workflow/specs/_template.md` to `.agent-workflow/specs/<name>.md`,
 
 The spec must have `status: open` and be merged to main before starting Phase B.
 
-### Start a task session
+### Option 1: Scripted (worktrees)
+
+```bash
+scripts/agent/implement-task.sh <task-name> <spec-file or spec-name>
+```
 
-From the repo root:
+This script:
+- creates a worktree at `~/agent-runs/{PROJECT_NAME}/worktrees/task-<slug>` on branch `agent/task/<slug>`
+- starts a Claude session inside that worktree
+- invokes `/implement-spec` with the given spec file
+
+Add `--interactive` to follow along in the same session and skip the automatic GitLab MR:
 
 ```bash
-scipts/agent/implement-task.sh <task-name> <spec-file or spec-name>
+scripts/agent/implement-task.sh --interactive <task-name> <spec-file or spec-name>
 ```
 
-This command: 
-- creates a worktree at `~/agent-runs/{PROJECT_NAME}/worktrees/task-<slug>` on branch `agent/spec/<slug>`
-- starts Claude session in `~/agent-runs/{PROJECT_NAME}/worktrees/task-<slug>` on branch `agent/spec/<slug>`
-- iniate `/implement-spec` skill from given <spec-file or spec-name>
-- this will follow the local GitLab workflow. Create the plan first, push it, and stop for approval (if needed).
+### Option 2: Direct (no worktrees)
+
+```bash
+# 1. Create and switch to a task branch from main
+git checkout main && git pull
+git checkout -b agent/task/<slug>
+
+# 2. Open Claude in the repo root
+claude
+
+# 3. Inside Claude, invoke the skill
+/implement-spec .agent-workflow/specs/<spec-file>.md
+```
+
+The agent takes it from there — plan, push, MR, wait for approval if `verification: true`.
 
 ### 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/`).
+4. After approval (or immediately if `verification: false`): implements the feature — in single-repo mode, code changes go directly in this repo; in meta-repo mode, changes go into the relevant `repos/<module>/` submodule(s) declared in `AGENTS.md`.
 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.
@@ -122,7 +170,7 @@ Reply in the same Claude session:
 Proceed with implementation.
 ```
 
-Or start a fresh session in the same worktree and say:
+Or start a fresh session (in the same worktree or the repo root on the same branch) and say:
 
 ```
 Use implement-spec skill for .agent-workflow/specs/<spec-file>.md. Plan is approved, proceed with implementation.
@@ -130,19 +178,27 @@ Use implement-spec skill for .agent-workflow/specs/<spec-file>.md. Plan is appro
 
 ---
 
-## Meta-repo specifics
+## Repo mode
+
+The repo mode is declared in `AGENTS.md`. Check it before starting any implementation.
 
-In case 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.
+**Single-repo:**
 
 | What | Where it lives |
 |------|---------------|
-| Spec, plan, docs, artifacts | `.agent-workflow/` in this meta repo |
-| Submodules code changes | `repos/` submodules in sepparate folders with their repositories |
-| Acceptance proof (runtime) | Runs inside the relevant submodule; artifacts stored here |
+| Spec, plan, docs, artifacts | `.agent-workflow/` in this repo |
+| Application code | This repo — commit and MR everything here |
+| Acceptance proof (runtime) | Run from the repo root; artifacts stored under `.agent-workflow/artifacts/` |
 
-A cross-cutting spec (touching multiple repos) results in one plan here and separate MRs in each affected sub-repo.
+**Meta-repo:**
+
+| What | Where it lives |
+|------|---------------|
+| Spec, plan, docs, artifacts | `.agent-workflow/` in this repo |
+| Application code | `repos/<module>/` submodules — see `AGENTS.md` for the full list |
+| Acceptance proof (runtime) | Run inside the relevant `repos/<module>/` directory; artifacts stored here |
 
-In case this is a single repo project, everything will live in this single root folder and repo.
+A cross-cutting spec (touching multiple submodules) results in one plan here and separate MRs in each affected `repos/<module>/` GitLab project.
 
 ---
 

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

@@ -42,9 +42,9 @@ chmod +x scripts/agent/*.sh
 
 ---
 
-## 3. Create the worktree root directory
+## 3. Create the worktree root directory *(optional — scripted workflow only)*
 
-Agent worktrees live outside the main repo clone:
+Only needed if you plan to use the bash scripts (`prepare-spec.sh`, `implement-task.sh`) that create git worktrees automatically. Skip this step if you prefer the direct workflow (manual branch + `claude` in the repo root).
 
 ```bash
 mkdir -p ~/agent-runs/{PROJECT_NAME}/worktrees
@@ -77,20 +77,38 @@ Claude Code will read `CLAUDE.md` and `.claude/rules/agentic-workflow.md` automa
 
 ## Running a spec session (Phase A)
 
-From the repo root (no worktree needed for spec prep):
-
+**Scripted (auto worktree + branch):**
 ```bash
-scripts/agent/prepare-spec <spec-name> <notion-link>
+scripts/agent/prepare-spec.sh <spec-name> <notion-link>
+
+# Add --interactive to follow along and skip automatic GitLab MR:
+scripts/agent/prepare-spec.sh --interactive <spec-name> <notion-link>
 ```
 
-The agent will create a branch `agent/spec/<slug>`, commit the spec, and open a GitLab MR.
+**Direct (manual branch, no worktree):**
+```bash
+git checkout -b agent/spec/<slug>
+claude
+# then inside Claude: /prepare-spec <notion-link>
+```
 
 ---
 
-## Running a implementation session (Phase B)
+## Running an implementation session (Phase B)
 
+**Scripted (auto worktree + branch):**
 ```bash
-scipts/agent/implement-task.sh <task-name> <spec-file or spec-name>
+scripts/agent/implement-task.sh <task-name> <spec-file or spec-name>
+
+# Add --interactive to follow along and skip automatic GitLab MR:
+scripts/agent/implement-task.sh --interactive <task-name> <spec-file or spec-name>
+```
+
+**Direct (manual branch, no worktree):**
+```bash
+git checkout -b agent/task/<slug>
+claude
+# then inside Claude: /implement-spec .agent-workflow/specs/<spec-file>.md
 ```
 
 ---

package/templates/scripts/agent/implement-task.sh

@@ -1,8 +1,20 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+INTERACTIVE=false
+
+# Parse flags
+POSITIONAL=()
+for arg in "$@"; do
+  case "$arg" in
+    --interactive) INTERACTIVE=true ;;
+    *) POSITIONAL+=("$arg") ;;
+  esac
+done
+set -- "${POSITIONAL[@]}"
+
 if [[ $# -lt 2 ]]; then
-  echo "Usage: $0 <slug> <spec_name>" >&2
+  echo "Usage: $0 [--interactive] <slug> <spec_name>" >&2
   exit 1
 fi
 
@@ -16,4 +28,10 @@ WORKTREE_DIR=$(echo "${OUTPUT}" | grep '^WORKTREE_DIR=' | cut -d= -f2-)
 
 echo "Worktree: ${WORKTREE_DIR}" >&2
 cd "${WORKTREE_DIR}"
-exec claude --dangerously-skip-permissions -p "use implement-spec skill from ${SPEC_NAME}"
+
+if [[ "$INTERACTIVE" == true ]]; then
+  echo "Starting interactive Claude session (GitLab flow disabled)..." >&2
+  exec claude --dangerously-skip-permissions --message "use implement-spec skill from ${SPEC_NAME}. Skip GitLab flow — do not push or open an MR."
+else
+  exec claude --dangerously-skip-permissions -p "use implement-spec skill from ${SPEC_NAME}"
+fi

package/templates/scripts/agent/prepare-spec.sh

@@ -1,8 +1,20 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+INTERACTIVE=false
+
+# Parse flags
+POSITIONAL=()
+for arg in "$@"; do
+  case "$arg" in
+    --interactive) INTERACTIVE=true ;;
+    *) POSITIONAL+=("$arg") ;;
+  esac
+done
+set -- "${POSITIONAL[@]}"
+
 if [[ $# -lt 2 ]]; then
-  echo "Usage: $0 <slug> <notion_url>" >&2
+  echo "Usage: $0 [--interactive] <slug> <notion_url>" >&2
   exit 1
 fi
 
@@ -16,4 +28,10 @@ WORKTREE_DIR=$(echo "${OUTPUT}" | grep '^WORKTREE_DIR=' | cut -d= -f2-)
 
 echo "Worktree: ${WORKTREE_DIR}" >&2
 cd "${WORKTREE_DIR}"
-exec claude --dangerously-skip-permissions -p "use prepare-spec skill from ${NOTION_URL}"
+
+if [[ "$INTERACTIVE" == true ]]; then
+  echo "Starting interactive Claude session (GitLab flow disabled)..." >&2
+  exec claude --dangerously-skip-permissions --message "use prepare-spec skill from ${NOTION_URL}. Skip GitLab flow — do not push or open an MR."
+else
+  exec claude --dangerously-skip-permissions -p "use prepare-spec skill from ${NOTION_URL}"
+fi