@codebehind/agent-workflow 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/templates/agents-workflow-dev-process.md +23 -48
  3. package/templates/agents-workflow-env-setup.md +11 -37
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codebehind/agent-workflow",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "Scaffold the agent-workflow spec-driven delivery framework into any repo",
5
5
  "type": "module",
6
6
  "bin": {
package/templates/agents-workflow-dev-process.md CHANGED
@@ -30,7 +30,7 @@ See `agents-workflow-env-setup.md` for initial setup.
30
30
 
31
31
  ## What is a spec?
32
32
 
33
- A **spec** is the authoritative description of what should be built and what "done" means. It lives in:
33
+ A **spec** is the authoritative description of WHAT should be built, WHY it should be buit and what "DONE" means. It lives in:
34
34
 
35
35
  ```
36
36
  .agent-workflow/specs/{name}.md
@@ -52,20 +52,24 @@ Use `_template.md` when creating specs by hand.
52
52
 
53
53
  ### Option 1: From a Notion page
54
54
 
55
- Start a **new Claude Code session** in the repo root worktree and say:
55
+ In the repo root worktree start following command (this will create new git worktree, branch and start new claude session with /prepare-spec skill):
56
56
 
57
- ```
58
- Use prepare-spec skill. Source: <notion-url>
57
+ ```bash
58
+ scripts/agent/prepare-spec <slug> <notion-link>
59
59
  ```
60
60
 
61
+ This command:
62
+ - creates a worktree at `~/agent-runs/{PROJECT_NAME}/worktrees/spec-<slug>` on branch `agent/spec/<slug>`
63
+ - starts Claude session in `~/agent-runs/{PROJECT_NAME}/worktrees/spec-<slug>` on branch `agent/spec/<slug>`
64
+ - iniate `/prepare-spec` skill from given <notion-link>
65
+
61
66
  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`.
62
67
 
63
68
  ### Option 2: From a description
64
69
 
70
+ TBD
65
71
  ```
66
- Use prepare-spec skill.
67
-
68
- <short title and bullet-point description of the feature>
72
+ # Still in progress...
69
73
  ```
70
74
 
71
75
  ### Option 3: By hand
@@ -74,10 +78,10 @@ Copy `.agent-workflow/specs/_template.md` to `.agent-workflow/specs/<name>.md`,
74
78
 
75
79
  ### After spec prep
76
80
 
77
- 1. Review the spec in the MR opened on branch `agent/spec/<slug>`.
81
+ 1. Review the spec in the MR or on branch `agent/spec/<slug>`.
78
82
  2. Edit if needed.
79
83
  3. Set `status: open` when ready for development (edit the file or ask the agent to flip it).
80
- 4. Merge the spec MR into main.
84
+ 4. Merge the spec MR into `default branch`.
81
85
 
82
86
  ---
83
87
 
@@ -90,24 +94,14 @@ The spec must have `status: open` and be merged to main before starting Phase B.
90
94
  From the repo root:
91
95
 
92
96
  ```bash
93
- scripts/agent/git-prepare-worktree.sh task <slug>
94
- ```
95
-
96
- This creates a worktree at `~/agent-runs/mjaumatish-meta/worktrees/task-<slug>` on branch `agent/task/<slug>`.
97
-
98
- Open Claude Code in that worktree:
99
-
100
- ```bash
101
- cd ~/agent-runs/mjaumatish-meta/worktrees/task-<slug>
102
- claude
97
+ scipts/agent/implement-task.sh <task-name> <spec-file or spec-name>
103
98
  ```
104
99
 
105
- Then instruct the agent:
106
-
107
- ```
108
- Use implement-spec skill for .agent-workflow/specs/<spec-file>.md.
109
- Follow the local GitLab workflow. Create the plan first, push it, and stop for approval.
110
- ```
100
+ This command:
101
+ - creates a worktree at `~/agent-runs/{PROJECT_NAME}/worktrees/task-<slug>` on branch `agent/spec/<slug>`
102
+ - starts Claude session in `~/agent-runs/{PROJECT_NAME}/worktrees/task-<slug>` on branch `agent/spec/<slug>`
103
+ - iniate `/implement-spec` skill from given <spec-file or spec-name>
104
+ - this will follow the local GitLab workflow. Create the plan first, push it, and stop for approval (if needed).
111
105
 
112
106
  ### What the agent does
113
107
 
@@ -138,18 +132,18 @@ Use implement-spec skill for .agent-workflow/specs/<spec-file>.md. Plan is appro
138
132
 
139
133
  ## Meta-repo specifics
140
134
 
141
- 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.
135
+ 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.
142
136
 
143
137
  | What | Where it lives |
144
138
  |------|---------------|
145
139
  | Spec, plan, docs, artifacts | `.agent-workflow/` in this meta repo |
146
- | Backend code changes | `backend/` submodule → MR in mjaumatish-backend |
147
- | Web code changes | `web/` submodule → MR in mjaumatish-web |
148
- | Mobile code changes | `mobile/` submodule → MR in mjaumatish-mobile |
140
+ | Submodules code changes | `repos/` submodules in sepparate folders with their repositories |
149
141
  | Acceptance proof (runtime) | Runs inside the relevant submodule; artifacts stored here |
150
142
 
151
143
  A cross-cutting spec (touching multiple repos) results in one plan here and separate MRs in each affected sub-repo.
152
144
 
145
+ In case this is a single repo project, everything will live in this single root folder and repo.
146
+
153
147
  ---
154
148
 
155
149
  ## Verification: checkpoints or autonomous
@@ -191,22 +185,3 @@ Scripts under `scripts/agent/` handle the GitLab integration:
191
185
  | `cleanup-worktree.sh` | Remove a worktree after work is merged |
192
186
 
193
187
  The agent uses these automatically when instructed to follow the local GitLab workflow.
194
-
195
- ---
196
-
197
- ## Quick reference
198
-
199
- | Concept | Rule |
200
- |---------|------|
201
- | Spec location | `.agent-workflow/specs/` in meta repo only |
202
- | Spec status | `draft` → author; `open` → implement; `done` → finished |
203
- | Phase A session | Any worktree; use `/prepare-spec` skill |
204
- | Phase B session | `~/agent-runs/mjaumatish-meta/worktrees/task-<slug>` |
205
- | Branch — spec | `agent/spec/<slug>` |
206
- | Branch — task | `agent/task/<slug>` |
207
- | Code changes | Inside submodule dirs (`backend/`, `web/`, `mobile/`) |
208
- | Verification | `true` = plan approval checkpoint (default); `false` = autonomous |
209
- | Acceptance proof | `true` = runtime evidence required (default); `false` = config/infra only |
210
- | Docs | `.agent-workflow/docs/` + add spec under **Covered Specs** |
211
- | Artifacts | `.agent-workflow/artifacts/acceptance-<spec-slug>-<YYYYMMDD>/` |
212
- | Done | Acceptance proof attached to MR → review → **merge** |
package/templates/agents-workflow-env-setup.md CHANGED
@@ -18,22 +18,7 @@ Install these tools before starting:
18
18
 
19
19
  ---
20
20
 
21
- ## 1. Clone with submodules
22
-
23
- ```bash
24
- git clone --recurse-submodules https://gitlab.com/codebehind/mjaumatish/mjaumatish-meta.git
25
- cd mjaumatish-meta
26
- ```
27
-
28
- Or if already cloned without submodules:
29
-
30
- ```bash
31
- ./scripts/bootstrap.sh
32
- ```
33
-
34
- ---
35
-
36
- ## 2. Authenticate with GitLab
21
+ ## 1. Authenticate with GitLab
37
22
 
38
23
  ```bash
39
24
  glab auth login
@@ -49,7 +34,7 @@ glab auth status
49
34
 
50
35
  ---
51
36
 
52
- ## 3. Make agent scripts executable
37
+ ## 2. Make agent scripts executable
53
38
 
54
39
  ```bash
55
40
  chmod +x scripts/agent/*.sh
@@ -57,17 +42,17 @@ chmod +x scripts/agent/*.sh
57
42
 
58
43
  ---
59
44
 
60
- ## 4. Create the worktree root directory
45
+ ## 3. Create the worktree root directory
61
46
 
62
47
  Agent worktrees live outside the main repo clone:
63
48
 
64
49
  ```bash
65
- mkdir -p ~/agent-runs/mjaumatish-meta/worktrees
50
+ mkdir -p ~/agent-runs/{PROJECT_NAME}/worktrees
66
51
  ```
67
52
 
68
53
  ---
69
54
 
70
- ## 5. Verify the default branch
55
+ ## 4. Verify the default branch
71
56
 
72
57
  The agent scripts auto-detect the default branch from origin. You can check it manually:
73
58
 
@@ -79,10 +64,10 @@ Should return `main`.
79
64
 
80
65
  ---
81
66
 
82
- ## 6. Open Claude Code in the repo root
67
+ ## 5. Open Claude Code in the repo root
83
68
 
84
69
  ```bash
85
- cd mjaumatish-meta
70
+ cd {PROJECT_FOLDER}
86
71
  claude
87
72
  ```
88
73
 
@@ -95,28 +80,17 @@ Claude Code will read `CLAUDE.md` and `.claude/rules/agentic-workflow.md` automa
95
80
  From the repo root (no worktree needed for spec prep):
96
81
 
97
82
  ```bash
98
- claude
99
- # then in the session:
100
- # Use prepare-spec skill. <description or Notion URL>
83
+ scripts/agent/prepare-spec <spec-name> <notion-link>
101
84
  ```
102
85
 
103
86
  The agent will create a branch `agent/spec/<slug>`, commit the spec, and open a GitLab MR.
104
87
 
105
88
  ---
106
89
 
107
- ## Running a task session (Phase B)
90
+ ## Running a implementation session (Phase B)
108
91
 
109
92
  ```bash
110
- # 1. Prepare a worktree for the task
111
- scripts/agent/git-prepare-worktree.sh task <slug>
112
-
113
- # 2. Open Claude Code in the worktree
114
- cd ~/agent-runs/mjaumatish-meta/worktrees/task-<slug>
115
- claude
116
-
117
- # 3. Instruct the agent
118
- # Use implement-spec skill for .agent-workflow/specs/<spec-file>.md.
119
- # Follow the local GitLab workflow. Create the plan, push it, stop for approval.
93
+ scipts/agent/implement-task.sh <task-name> <spec-file or spec-name>
120
94
  ```
121
95
 
122
96
  ---
@@ -124,7 +98,7 @@ claude
124
98
  ## Cleanup after a branch is merged
125
99
 
126
100
  ```bash
127
- scripts/agent/cleanup-worktree.sh <slug>
101
+ scripts/agent/cleanup-worktree.sh <task-name>
128
102
  ```
129
103
 
130
104
  ---