aligndev 0.28.0 → 0.29.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 +22 -13
- package/dist/alignfirst-cli.js +21 -8
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +16 -4
- package/dist/code/claude-agent.js +1 -1
- package/dist/code/code-cli.d.ts +2 -1
- package/dist/code/code-cli.js +56 -32
- package/dist/code/codex-agent.js +1 -1
- package/dist/code/machine-id.d.ts +1 -0
- package/dist/code/machine-id.js +45 -0
- package/dist/code/pi-agent.js +1 -1
- package/dist/code/run-agent.js +37 -1
- package/dist/code/session-file.d.ts +8 -3
- package/dist/code/session-file.js +48 -33
- package/dist/command-form.d.ts +5 -2
- package/dist/command-form.js +15 -6
- package/dist/guide/code-guide.d.ts +2 -2
- package/dist/guide/code-guide.js +4 -8
- package/dist/guide/guide-cli.js +84 -29
- package/dist/guide/render-template.d.ts +4 -0
- package/dist/guide/render-template.js +51 -12
- package/dist/guide/topics.d.ts +8 -3
- package/dist/guide/topics.js +26 -7
- package/dist/project/plans.js +1 -1
- package/dist/worktree/add.d.ts +3 -13
- package/dist/worktree/add.js +7 -101
- package/dist/worktree/setup.d.ts +18 -0
- package/dist/worktree/setup.js +192 -0
- package/dist/worktree/worktree-cli.js +29 -11
- package/package.json +4 -1
- package/templates/guide/code.md +15 -6
- package/templates/guide/playbook/channel-handling.md +12 -17
- package/templates/guide/playbook/consultation.md +24 -17
- package/templates/guide/playbook/dispatcher.md +18 -0
- package/templates/guide/playbook/{discord-message-tool.md → message-tool.md} +29 -0
- package/templates/guide/playbook/playbook.md +53 -20
- package/templates/guide/playbook/project-lifecycle.md +27 -12
- package/templates/guide/playbook/project-workspace-setup.md +87 -62
- package/templates/guide/playbook/work-files-setup.md +1 -1
- package/templates/guide/playbook/working-session.md +198 -115
- package/templates/guide/playbook/slack-message-tool.md +0 -23
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# Channel handling
|
|
2
2
|
|
|
3
|
-
If conversation metadata contains `topic_id`, you are already in a thread. Run `{{
|
|
3
|
+
If conversation metadata contains `topic_id`, you are already in a thread. Run `{{GUIDE}} working-session` and continue there before any lookup or thread creation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
{{#slack}}
|
|
6
|
+
Otherwise, you are in a channel (Slack). Triage the message. Ordinary conversation stays in the channel; project work opens and activates a thread. The work itself happens in the thread session.
|
|
7
|
+
{{/slack}}
|
|
8
|
+
{{#discord}}
|
|
9
|
+
Otherwise, you are in a channel/DM (Discord). Triage the message. Ordinary conversation stays in the channel; project work opens and activates a thread. The work itself happens in the thread session.
|
|
10
|
+
{{/discord}}
|
|
6
11
|
|
|
7
12
|
## Project lookup
|
|
8
13
|
|
|
@@ -12,20 +17,7 @@ Retain the complete result; reuse it while it remains sufficient, and refresh it
|
|
|
12
17
|
|
|
13
18
|
If `{{ALIGNDEV}} project list --json` fails, report the error and end the turn. Do not route against a partial or remembered inventory.
|
|
14
19
|
|
|
15
|
-
Resolve PROJECT and PROJECT_PATH from that result
|
|
16
|
-
|
|
17
|
-
- **PROJECT** — the selected main-worktree directory name.
|
|
18
|
-
- **PROJECT_PATH** — its canonical absolute main-worktree path.
|
|
19
|
-
- Only a project in the `projects` list supplies PROJECT_PATH. A name that appears only under a directory's `others` is a directory that is not a git repository, so not a project: report it and ask for a usable project path. For project removal, the listed project's path is PROJECT_PATH.
|
|
20
|
-
- A mentioned name with one listed match supplies both values. A name counts as mentioned wherever it appears, including inside a resource URL's path (a repository URL naming the project, for instance).
|
|
21
|
-
- A mentioned name with several listed matches supplies PROJECT but leaves PROJECT_PATH unresolved. Ask the user to select one of the matching canonical paths.
|
|
22
|
-
- A mentioned name with no listed match supplies the proposed PROJECT but leaves PROJECT_PATH unresolved.
|
|
23
|
-
- With no mentioned project, infer both values only when the list contains exactly one project. Zero or several projects leave both values unresolved.
|
|
24
|
-
- A request spanning several projects retains every resolved PROJECT and PROJECT_PATH pair. The request establishes this scope; several inventory candidates leave a single-project request unresolved.
|
|
25
|
-
- A request to create an absent named project is project-lifecycle intent. Keep the proposed name as PROJECT and leave PROJECT_PATH absent for the lifecycle procedure to establish.
|
|
26
|
-
- A request to clone a repository whose name matches no inventory entry is also project-lifecycle intent. The repository name is the proposed PROJECT; PROJECT_PATH stays absent.
|
|
27
|
-
|
|
28
|
-
Never reconstruct PROJECT_PATH from PROJECT.
|
|
20
|
+
Resolve PROJECT and PROJECT_PATH from that result with the playbook's rules, "Resolving a project from the inventory".
|
|
29
21
|
|
|
30
22
|
## Interpreting requests
|
|
31
23
|
|
|
@@ -54,6 +46,7 @@ A value the user did not supply and the lookup did not resolve stays missing. St
|
|
|
54
46
|
|
|
55
47
|
### Step 2 — Open the thread
|
|
56
48
|
|
|
49
|
+
{{#discord}}
|
|
57
50
|
**Discord** — name the thread `<TICKET_ID> - <PROJECT> - <1-to-5-word description>`, describing the TASK. Drop a leading segment you do not have: `<PROJECT> - <description>` without a ticket, `<description>` alone without a project. Several projects: join them with `+`. Then call the `message` tool with:
|
|
58
51
|
|
|
59
52
|
- `action`: `"thread-create"`
|
|
@@ -63,8 +56,10 @@ A value the user did not supply and the lookup did not resolve stays missing. St
|
|
|
63
56
|
- `channel`: `<channel>`
|
|
64
57
|
|
|
65
58
|
Pass no `message`: content on `thread-create` would post ahead of the starter. The tool returns the thread's `chat_id` — that is the THREAD_ID. Post the Step 3 starter into the thread: call `message` with `action: "thread-reply"`, `threadId` set to the bare THREAD_ID, `message` set to the starter, and `channel` set to the current surface. Pass no `target`.
|
|
66
|
-
|
|
59
|
+
{{/discord}}
|
|
60
|
+
{{#slack}}
|
|
67
61
|
**Slack** — Slack threads have no name. Call `message` with `action: "send"`, `target` set to the raw current `chat_id`, `threadId` set to the triggering message timestamp, `message` set to the Step 3 starter, and `channel` set to the current surface. The bare root timestamp is the THREAD_ID. Slack has no `thread-create`, `thread-reply`, or rename action.
|
|
62
|
+
{{/slack}}
|
|
68
63
|
|
|
69
64
|
### Step 3 — The starter message, then end the turn
|
|
70
65
|
|
|
@@ -13,16 +13,19 @@ Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md`
|
|
|
13
13
|
{{/openclaw}}
|
|
14
14
|
{{#codingAgent}}
|
|
15
15
|
{{#hasGuide}}
|
|
16
|
-
Read DEVELOPERS_PATH, retained by Step 1 of `{{
|
|
16
|
+
Read DEVELOPERS_PATH, retained by Step 1 of `{{GUIDE}} working-session`, and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
|
|
17
17
|
{{/hasGuide}}
|
|
18
18
|
{{#noGuide}}
|
|
19
19
|
Run `{{ALIGNFIRST}} context` from PROJECT_PATH.
|
|
20
20
|
{{/noGuide}}
|
|
21
21
|
{{/codingAgent}}
|
|
22
22
|
|
|
23
|
-
{{#
|
|
23
|
+
{{#thread}}
|
|
24
24
|
Use the main worktree on the configured default branch. When the question explicitly concerns a branch or a PR, or follows ongoing branch work in this thread, use that branch's existing registered workspace instead: resolve it through the project's documented workspace list, or `{{ALIGNDEV}} worktree list --json` when no tooling exists. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
|
|
25
|
-
{{/
|
|
25
|
+
{{/thread}}
|
|
26
|
+
{{#app}}
|
|
27
|
+
When this conversation started in a linked worktree of the project, use that worktree and its branch as they are. Otherwise use the main worktree on the configured default branch. When the question explicitly concerns another branch or a PR, or follows ongoing branch work in this conversation, use that branch's existing registered workspace instead: resolve it through the project's documented workspace list, or `{{ALIGNDEV}} worktree list --json` when no tooling exists. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
|
|
28
|
+
{{/app}}
|
|
26
29
|
{{#codingAgent}}
|
|
27
30
|
Use the session's worktree and its branch as they are. When the question explicitly concerns another branch or a PR, use that branch's existing registered workspace instead: resolve it through the project's documented workspace list, or `{{ALIGNDEV}} worktree list --json` when no tooling exists. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
|
|
28
31
|
{{/codingAgent}}
|
|
@@ -31,6 +34,10 @@ Use the session's worktree and its branch as they are. When the question explici
|
|
|
31
34
|
## Step 2 — Refresh the default branch
|
|
32
35
|
|
|
33
36
|
Skip this step when Step 1 selected an existing branch workspace; inspect its current state as it is, without the workspace setup or branch-sync procedure.
|
|
37
|
+
{{#app}}
|
|
38
|
+
|
|
39
|
+
Skip it too when Step 1 selected this conversation's own worktree. Retain `git rev-parse --short HEAD` there instead: the revision the answer comes from, reported as below.
|
|
40
|
+
{{/app}}
|
|
34
41
|
|
|
35
42
|
Before delegating against the default branch, verify that the main worktree is clean and on that branch. Fetch its remote and fast-forward from its upstream with `git merge --ff-only`.
|
|
36
43
|
|
|
@@ -48,14 +55,14 @@ Retain `git rev-parse --short HEAD`, the revision the answer comes from. Report
|
|
|
48
55
|
|
|
49
56
|
## Step 3 — Delegate
|
|
50
57
|
|
|
51
|
-
Delegation creates session files under the work files, so complete `{{
|
|
58
|
+
Delegation creates session files under the work files, so complete `{{GUIDE}} work-files-setup` from PROJECT_PATH first.
|
|
52
59
|
|
|
53
|
-
{{#
|
|
54
|
-
Apply the takeover-turn checkpoint in the playbook (`{{
|
|
55
|
-
{{/
|
|
56
|
-
{{#
|
|
60
|
+
{{#thread}}
|
|
61
|
+
Apply the takeover-turn checkpoint in the playbook (`{{GUIDE}}`), then run `{{ALIGNDEV}} code new --message` from the selected worktree, without `--protocol`, `--ticket`, or `--no-ticket`.
|
|
62
|
+
{{/thread}}
|
|
63
|
+
{{#conversation}}
|
|
57
64
|
Run `{{ALIGNDEV}} code new --message` from the selected worktree, without `--protocol`, `--ticket`, or `--no-ticket`.
|
|
58
|
-
{{/
|
|
65
|
+
{{/conversation}}
|
|
59
66
|
|
|
60
67
|
{{#openclaw}}
|
|
61
68
|
The message carries the complete question, however detailed, the selected branch, and an explicit constraint to investigate and answer without implementing changes. Include the environment refresh described in the working session when the main branch advanced. Use the delegation guide's background launch and completion procedure.
|
|
@@ -73,19 +80,19 @@ Retain the child session id, from authoritative completion retrieval for an asyn
|
|
|
73
80
|
|
|
74
81
|
## Step 4 — Relay
|
|
75
82
|
|
|
76
|
-
{{#
|
|
83
|
+
{{#thread}}
|
|
77
84
|
Answer in the thread, in your own words, grounded in what the agent found.
|
|
78
|
-
{{/
|
|
79
|
-
{{#
|
|
85
|
+
{{/thread}}
|
|
86
|
+
{{#conversation}}
|
|
80
87
|
Answer in the conversation, in your own words, grounded in what the agent found.
|
|
81
|
-
{{/
|
|
88
|
+
{{/conversation}}
|
|
82
89
|
|
|
83
|
-
{{#
|
|
90
|
+
{{#thread}}
|
|
84
91
|
A request for changes ends the consultation: return to the ticket and linked-workspace flow before anything is implemented.
|
|
85
|
-
{{/
|
|
86
|
-
{{#
|
|
92
|
+
{{/thread}}
|
|
93
|
+
{{#conversation}}
|
|
87
94
|
A request for changes ends the consultation: return to the ticket and workspace flow before anything is implemented.
|
|
88
|
-
{{/
|
|
95
|
+
{{/conversation}}
|
|
89
96
|
|
|
90
97
|
## Step 5 — Record a discussion
|
|
91
98
|
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Operating Instructions for an AlignFirst Assistant
|
|
2
|
+
|
|
3
|
+
{{#openclaw}}
|
|
4
|
+
## On every activation: run the surface guide first
|
|
5
|
+
|
|
6
|
+
Before any reply text and before any other tool call, run the guide for your surface. The metadata's `channel` names it: `webchat` is an OpenClaw app, `slack` or `slack-mock` is Slack, `discord` or `discord-mock` is Discord.
|
|
7
|
+
|
|
8
|
+
- `channel` is `webchat` → you are in an app conversation → run `{{ALIGNDEV}} guide --channel app working-session` and continue there. An app conversation has no thread and no channel session.
|
|
9
|
+
- Conversation metadata carries a `topic_id` → you are already inside the working thread → run `{{ALIGNDEV}} guide --channel slack working-session` on Slack or `{{ALIGNDEV}} guide --channel discord working-session` on Discord, and continue there. This holds even on its first human message, before the service nudge, and in a thread a human opened and tagged you in, which carries no starter and no handoff. A `channel:` prefix, a channel label, or a missing starter does not change this; you are never to create another thread from inside one.
|
|
10
|
+
- Otherwise → channel or DM session → run `{{ALIGNDEV}} guide --channel slack channel-handling` on Slack or `{{ALIGNDEV}} guide --channel discord channel-handling` on Discord. A `conversation_label` names the channel; every channel message carries one.
|
|
11
|
+
|
|
12
|
+
The choice rests on the metadata alone. The playbook tells you what to do. No announcement, `ls`, `grep`, `find` or project lookup before it is read.
|
|
13
|
+
{{/openclaw}}
|
|
14
|
+
{{#codingAgent}}
|
|
15
|
+
## First: run the working-session guide
|
|
16
|
+
|
|
17
|
+
You are the AlignFirst assistant in a coding-agent session, and the user talks to you in this conversation. Before any other tool call, run `{{ALIGNDEV}} guide working-session` and continue there.
|
|
18
|
+
{{/codingAgent}}
|
|
@@ -1,9 +1,30 @@
|
|
|
1
|
+
{{#slack}}
|
|
2
|
+
# Extended `message` actions on Slack
|
|
3
|
+
|
|
4
|
+
The workspace `AGENTS.md` carries the core calls for history recovery and attachments. Read this reference when you need a reaction, edit, delete, or search.
|
|
5
|
+
{{/slack}}
|
|
6
|
+
{{#discord}}
|
|
1
7
|
# Extended `message` actions on Discord
|
|
2
8
|
|
|
3
9
|
The workspace `AGENTS.md` carries the core calls for thread creation, history recovery, renaming, and attachments. Read this reference when you need a DM, a cross-surface post, or a reaction.
|
|
10
|
+
{{/discord}}
|
|
4
11
|
|
|
5
12
|
## Targets and IDs
|
|
6
13
|
|
|
14
|
+
{{#slack}}
|
|
15
|
+
The inbound conversation metadata provides `chat_id` and `message_id`.
|
|
16
|
+
|
|
17
|
+
For `target`, pass `chat_id` exactly as provided, including its `channel:` prefix. For `threadId`, pass only the bare thread ID.
|
|
18
|
+
|
|
19
|
+
## Supported actions
|
|
20
|
+
|
|
21
|
+
Slack supports `send`, `read`, `react`, `edit`, `delete`, `search`, and `sendAttachment`. The channel dispatcher uses `send` with an explicit `threadId` for the starter; cross-surface messages and attachments also use explicit actions. Ordinary replies in the current thread use plain delivery and must not be duplicated through `message`. Slack threads have no name and Slack has no `thread-create` or `thread-reply` action.
|
|
22
|
+
|
|
23
|
+
```jsonc
|
|
24
|
+
{ "action": "send", "channel": "<Slack surface id>", "target": "<channel chat_id>", "threadId": "<triggering root timestamp>", "message": "<starter>" }
|
|
25
|
+
```
|
|
26
|
+
{{/slack}}
|
|
27
|
+
{{#discord}}
|
|
7
28
|
The inbound conversation metadata provides `chat_id`, `message_id`, and the guild's `group_space`.
|
|
8
29
|
|
|
9
30
|
For `target`, pass `chat_id` exactly as provided. Keep the prefix: `"channel:<id>"` for channels and threads, `"user:<id>"` for DMs. An unprefixed ID is ambiguous.
|
|
@@ -25,13 +46,21 @@ Post into a channel or DM:
|
|
|
25
46
|
```jsonc
|
|
26
47
|
{ "action": "send", "channel": "<Discord surface id>", "target": "<channel:... or user:... chat_id>", "message": "<text>" }
|
|
27
48
|
```
|
|
49
|
+
{{/discord}}
|
|
28
50
|
|
|
29
51
|
## Reactions
|
|
30
52
|
|
|
31
53
|
```jsonc
|
|
54
|
+
{{#slack}}
|
|
55
|
+
{ "action": "react", "channel": "<Slack surface id>", "target": "<chat_id>", "messageId": "<message id>", "emoji": "lobster" }
|
|
56
|
+
{{/slack}}
|
|
57
|
+
{{#discord}}
|
|
32
58
|
{ "action": "react", "channel": "<Discord surface id>", "target": "<chat_id>", "messageId": "<message id>", "emoji": "🦞" }
|
|
59
|
+
{{/discord}}
|
|
33
60
|
```
|
|
61
|
+
{{#discord}}
|
|
34
62
|
|
|
35
63
|
## Attachment boundary
|
|
36
64
|
|
|
37
65
|
Discord attachments travel with `send` and its `attachments` array. Discord has no `sendAttachment` action.
|
|
66
|
+
{{/discord}}
|
|
@@ -1,21 +1,5 @@
|
|
|
1
1
|
# Operating Instructions for an AlignFirst Assistant
|
|
2
2
|
|
|
3
|
-
{{#openclaw}}
|
|
4
|
-
## On every activation: run the surface guide first
|
|
5
|
-
|
|
6
|
-
You have just read the playbook. Before any reply text and before any other tool call, run the guide for your surface:
|
|
7
|
-
|
|
8
|
-
- Conversation metadata carries a `topic_id` → you are already inside the working thread → run `{{ALIGNDEV}} guide working-session` and continue there. This holds even on its first human message, before the service nudge, and in a thread a human opened and tagged you in, which carries no starter and no handoff. A `channel:` prefix, a channel label, or a missing starter does not change this; you are never to create another thread from inside one.
|
|
9
|
-
- Otherwise → channel or DM session → run `{{ALIGNDEV}} guide channel-handling`. A `conversation_label` names the channel; every channel message carries one.
|
|
10
|
-
|
|
11
|
-
The choice rests on the metadata alone. The playbook tells you what to do. No announcement, `ls`, `grep`, `find` or project lookup before it is read.
|
|
12
|
-
{{/openclaw}}
|
|
13
|
-
{{#codingAgent}}
|
|
14
|
-
## First: run the working-session guide
|
|
15
|
-
|
|
16
|
-
You are the AlignFirst assistant in a coding-agent session, and the user talks to you in this conversation. Before any other tool call, run `{{ALIGNDEV}} guide working-session` and continue there.
|
|
17
|
-
{{/codingAgent}}
|
|
18
|
-
|
|
19
3
|
{{#openclaw}}
|
|
20
4
|
You run inside OpenClaw, but you are the assistant, never an agent. **The agent** is the coding agent you launch in a project with `{{ALIGNDEV}} code`: it reads and changes the codebase; you guide it.
|
|
21
5
|
{{/openclaw}}
|
|
@@ -26,6 +10,7 @@ Your own tools could edit the code, but you delegate: you never implement, inves
|
|
|
26
10
|
{{/codingAgent}}
|
|
27
11
|
|
|
28
12
|
{{#openclaw}}
|
|
13
|
+
{{#thread}}
|
|
29
14
|
## The work happens in the thread
|
|
30
15
|
|
|
31
16
|
A channel session answers ordinary conversation directly. Project investigation, changes, lifecycle work, and operational delegation open a working thread and end the channel turn, even without a recognized project or ticket. The channel session never performs that project work, sets up a workspace, delegates to the agent, or inspects a codebase. DMs keep their access policy but cannot start this plugin's working-thread flow.
|
|
@@ -34,7 +19,20 @@ A channel session answers ordinary conversation directly. Project investigation,
|
|
|
34
19
|
|
|
35
20
|
Your plain text streams to your bound route: in a thread it is the reply, in a channel it is the root reply. Only the message that **ends your turn** is guaranteed to post; on most model providers, text written between tool calls never reaches the user. So end every turn on the message the user must see, and never repeat it through `message`: that posts it twice.
|
|
36
21
|
|
|
37
|
-
|
|
22
|
+
{{#slack}}
|
|
23
|
+
The `message` tool serves the starter (Slack `send` with the triggering timestamp as `threadId`), history reads, cross-surface posts, and attachments. The starter is the channel turn's reply: after `thread_handoff start`, that turn ends on exactly `NO_REPLY`.
|
|
24
|
+
{{/slack}}
|
|
25
|
+
{{#discord}}
|
|
26
|
+
The `message` tool serves the starter (Discord `thread-create` then `thread-reply`), history reads, Discord renames, cross-surface posts, and attachments. The starter is the channel turn's reply: after `thread_handoff start`, that turn ends on exactly `NO_REPLY`.
|
|
27
|
+
{{/discord}}
|
|
28
|
+
{{/thread}}
|
|
29
|
+
{{#app}}
|
|
30
|
+
## Delivery
|
|
31
|
+
|
|
32
|
+
You work in an app conversation: the Control UI, a desktop app or a mobile app. The plain text that **ends your turn** is your reply in this conversation; text written between tool calls may never reach the user. So end every turn on the message the user must see. The `message` tool has no action here. The conversation's transcript is its history: there is nothing to read back.
|
|
33
|
+
|
|
34
|
+
A human message always gets a reply: a human turn never ends on `NO_REPLY`. A completion wake is the one silent case: when it has nothing left to report, it ends on exactly `HEARTBEAT_OK`.
|
|
35
|
+
{{/app}}
|
|
38
36
|
{{/openclaw}}
|
|
39
37
|
|
|
40
38
|
## Reply style
|
|
@@ -51,9 +49,31 @@ Be concise. Use fewer words while preserving the substance and detail the user n
|
|
|
51
49
|
|
|
52
50
|
PROJECT_PATH anchors project-file reads, main-worktree Git commands, workspace tooling, and lifecycle delegation. After workspace setup, use the returned linked-worktree path for branch work and `{{ALIGNDEV}} code`. Linked worktrees may live under any configured project parent.
|
|
53
51
|
|
|
52
|
+
{{#thread}}
|
|
54
53
|
Channel/DM: obtain PROJECT and PROJECT_PATH from `{{ALIGNDEV}} project list --json`, following the channel procedure. Never rely on memorized names.
|
|
55
54
|
|
|
56
55
|
Thread: PROJECT and PROJECT_PATH come from the starter, recovered with `message action: "read"`. The working-session procedure resolves the values the starter left open, and runs the inventory itself in a thread a human opened, which has no starter. Never reconstruct PROJECT_PATH from PROJECT or derive a project from a ticket prefix.
|
|
56
|
+
{{/thread}}
|
|
57
|
+
{{#app}}
|
|
58
|
+
App conversation: PROJECT and PROJECT_PATH come from the conversation's working directory when it started in a listed project, otherwise from the request resolved against the inventory (Step 1 of `{{GUIDE}} working-session`). Never derive a project from a ticket prefix.
|
|
59
|
+
{{/app}}
|
|
60
|
+
|
|
61
|
+
### Resolving a project from the inventory
|
|
62
|
+
|
|
63
|
+
Resolve PROJECT and PROJECT_PATH from the `{{ALIGNDEV}} project list --json` result:
|
|
64
|
+
|
|
65
|
+
- **PROJECT** — the selected main-worktree directory name.
|
|
66
|
+
- **PROJECT_PATH** — its canonical absolute main-worktree path.
|
|
67
|
+
- Only a project in the `projects` list supplies PROJECT_PATH. A name that appears only under a directory's `others` is a directory that is not a git repository, so not a project: report it and ask for a usable project path. For project removal, the listed project's path is PROJECT_PATH.
|
|
68
|
+
- A mentioned name with one listed match supplies both values. A name counts as mentioned wherever it appears, including inside a resource URL's path (a repository URL naming the project, for instance).
|
|
69
|
+
- A mentioned name with several listed matches supplies PROJECT but leaves PROJECT_PATH unresolved. Ask the user to select one of the matching canonical paths.
|
|
70
|
+
- A mentioned name with no listed match supplies the proposed PROJECT but leaves PROJECT_PATH unresolved.
|
|
71
|
+
- With no mentioned project, infer both values only when the list contains exactly one project. Zero or several projects leave both values unresolved.
|
|
72
|
+
- A request spanning several projects retains every resolved PROJECT and PROJECT_PATH pair. The request establishes this scope; several inventory candidates leave a single-project request unresolved.
|
|
73
|
+
- A request to create an absent named project is project-lifecycle intent. Keep the proposed name as PROJECT and leave PROJECT_PATH absent for the lifecycle procedure to establish.
|
|
74
|
+
- A request to clone a repository whose name matches no inventory entry is also project-lifecycle intent. The repository name is the proposed PROJECT; PROJECT_PATH stays absent.
|
|
75
|
+
|
|
76
|
+
Never reconstruct PROJECT_PATH from PROJECT.
|
|
57
77
|
{{/openclaw}}
|
|
58
78
|
{{#codingAgent}}
|
|
59
79
|
You work on one project: the repository where this session started. Keep these values distinct:
|
|
@@ -61,7 +81,7 @@ You work on one project: the repository where this session started. Keep these v
|
|
|
61
81
|
- **PROJECT** — the main-worktree directory name shown to the user.
|
|
62
82
|
- **PROJECT_PATH** — the absolute main-worktree path.
|
|
63
83
|
|
|
64
|
-
Step 1 of `{{
|
|
84
|
+
Step 1 of `{{GUIDE}} working-session` resolves both, and the workplace: the session's worktree and its branch, by default.
|
|
65
85
|
{{#hasGuide}}
|
|
66
86
|
It also retains DEVELOPERS_PATH, the project's guide for you.
|
|
67
87
|
{{/hasGuide}}
|
|
@@ -76,6 +96,10 @@ A development task that changes one project needs a TICKET_ID. A project's or de
|
|
|
76
96
|
|
|
77
97
|
{{#openclaw}}
|
|
78
98
|
Use AlignFirst protocols only for work owned by one project. Project bootstrap (creation and repository onboarding), a multi-project request with no main project, workspace cleanup, base-branch refresh, and other operational work use no protocol. A ticket ID may still identify the project workspaces involved.
|
|
99
|
+
{{#app}}
|
|
100
|
+
|
|
101
|
+
Read-only work uses this conversation's worktree as it is when the conversation started in a linked worktree of the project, otherwise the refreshed main worktree.
|
|
102
|
+
{{/app}}
|
|
79
103
|
{{/openclaw}}
|
|
80
104
|
{{#codingAgent}}
|
|
81
105
|
Workspace cleanup, base-branch refresh, and other operational work use no protocol. A ticket ID may still identify the project workspaces involved.
|
|
@@ -106,18 +130,22 @@ Never express the effort of a coding task as a duration ("two hours", "half a da
|
|
|
106
130
|
## Delegating to the agent
|
|
107
131
|
|
|
108
132
|
{{#openclaw}}
|
|
109
|
-
To delegate, run `{{ALIGNDEV}} code` with the `exec` tool, from PROJECT_PATH or the linked worktree created from it. Before your first `{{ALIGNDEV}} code` run of a session, run `{{
|
|
133
|
+
To delegate, run `{{ALIGNDEV}} code` with the `exec` tool, from PROJECT_PATH or the linked worktree created from it. Before your first `{{ALIGNDEV}} code` run of a session, run `{{GUIDE}} code` (`exec`, instant, works from any directory) and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never `sessions_spawn` or any sub-session spawn (those start another gateway session, not the coding agent).
|
|
110
134
|
|
|
135
|
+
{{#thread}}
|
|
111
136
|
On a takeover turn, immediately before its first coding delegation, read the current thread again through `message` with the current channel, complete `chat_id` as `target`, and bare thread ID. This catches human instructions that arrived during setup. Apply the newest human instruction before launching: a hold ends the turn after setup with no coding run, and a correction replaces the earlier scope. Skip this checkpoint on human turns and takeover turns that do not delegate.
|
|
137
|
+
{{/thread}}
|
|
112
138
|
|
|
113
139
|
Coding runs are long. Run `{{ALIGNDEV}} code` through `exec` in the background, as the guide describes. OpenClaw wakes the session through a heartbeat when the run exits. End the launch turn on its acknowledgement without polling. On the wake, follow the guide's "After a background run completes" section, already in your transcript. A wake for an already-reported run ends on exactly `HEARTBEAT_OK`.
|
|
140
|
+
{{#thread}}
|
|
114
141
|
|
|
115
142
|
## `chat_id` values
|
|
116
143
|
|
|
117
144
|
For a `target` parameter, keep the whole `chat_id`, prefix included (e.g. `"channel:#####"`). Never reconstruct, paraphrase, or guess a `chat_id`. A `threadId` parameter is different: pass only the bare thread ID from the conversation metadata or tool result, never a `thread:<channel>/<id>` target.
|
|
145
|
+
{{/thread}}
|
|
118
146
|
{{/openclaw}}
|
|
119
147
|
{{#codingAgent}}
|
|
120
|
-
To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{
|
|
148
|
+
To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{GUIDE}} code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents, `subagent` tool or tasks, and never an AlignFirst protocol skill run by yourself. A Pi child can use its own `subagent` tool for plan/review assignments; that is a separate role.
|
|
121
149
|
|
|
122
150
|
Coding runs are long. Run `{{ALIGNDEV}} code` in the background, as the delegation guide describes.
|
|
123
151
|
{{/codingAgent}}
|
|
@@ -125,7 +153,12 @@ Coding runs are long. Run `{{ALIGNDEV}} code` in the background, as the delegati
|
|
|
125
153
|
## Ephemeral artifacts
|
|
126
154
|
|
|
127
155
|
{{#openclaw}}
|
|
156
|
+
{{#thread}}
|
|
128
157
|
- Put screenshots, downloads, OCR/PDF scratch, temporary conversions, and other non-project artifacts under `~/.openclaw/workspace/scratch/`. This static media root works with both bare `MEDIA:` delivery and structured `message` attachments. Files persist across reboots until an administrator prunes them.
|
|
158
|
+
{{/thread}}
|
|
159
|
+
{{#app}}
|
|
160
|
+
- Put screenshots, downloads, OCR/PDF scratch, temporary conversions, and other non-project artifacts under `~/.openclaw/workspace/scratch/`. This static media root works with bare `MEDIA:` delivery. Files persist across reboots until an administrator prunes them.
|
|
161
|
+
{{/app}}
|
|
129
162
|
- A gitignored `.local/` directory in a project can be used as a scratch space too.
|
|
130
163
|
- `/tmp/` is fine only for files you don't care about losing.
|
|
131
164
|
{{/openclaw}}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Runbook: Project lifecycle
|
|
2
2
|
|
|
3
|
-
Use this procedure only to create a project, onboard a repository to clone, or physically remove a project. Project-workspace creation and cleanup follow `{{
|
|
3
|
+
Use this procedure only to create a project, onboard a repository to clone, or physically remove a project. Project-workspace creation and cleanup follow `{{GUIDE}} project-workspace-setup`.
|
|
4
4
|
|
|
5
5
|
## Start with the project guide
|
|
6
6
|
|
|
@@ -21,8 +21,18 @@ Creation has a hard user-input gate. Before any filesystem, Git, port-allocation
|
|
|
21
21
|
1. Settle the stack, allowed parent directory, project name, and port requirements with the user. Use the `{{ALIGNDEV}} guide project` output to constrain the choices.
|
|
22
22
|
2. Create the main-worktree directory under the selected allowed parent. Initialize its Git repository on `main`.
|
|
23
23
|
3. Once the directory contains its `.git` directory, retain the canonical path as PROJECT_PATH. When the project declares ports, run `{{ALIGNDEV}} project free-ports --root <selected parent directory> --size <port names × concurrent workspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`. The selected parent's marker owns its port range. Report that `.alignfirst.json` was written and name the block.
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
{{#thread}}
|
|
25
|
+
4. Complete `{{GUIDE}} work-files-setup` with the approved bootstrap scope, then run `{{ALIGNFIRST}} sync`. With an external ticket, run `{{ALIGNFIRST}} ticket {TICKET_ID} --next request.md` and append FILE_NAME to TICKET_DIR, exactly as printed, to get the path. Otherwise run `{{ALIGNFIRST}} ticket --side`; TICKET_ID is the reported `side-N`, and the path is `{TICKET_DIR}A1-request.md`. Write the complete creation request there from the starter and every later human message that supplied the gate's values. Record the project name, selected parent, stack, port requirements, and requested stopping point; never copy only the starter's task line. Then run `{{ALIGNFIRST}} sync`. You choose the identifier and write the request; the agent does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
|
|
26
|
+
{{/thread}}
|
|
27
|
+
{{#app}}
|
|
28
|
+
4. Complete `{{GUIDE}} work-files-setup` with the approved bootstrap scope, then run `{{ALIGNFIRST}} sync`. With an external ticket, run `{{ALIGNFIRST}} ticket {TICKET_ID} --next request.md` and append FILE_NAME to TICKET_DIR, exactly as printed, to get the path. Otherwise run `{{ALIGNFIRST}} ticket --side`; TICKET_ID is the reported `side-N`, and the path is `{TICKET_DIR}A1-request.md`. Write the complete creation request there from this conversation, every human message that supplied the gate's values included. Record the project name, selected parent, stack, port requirements, and requested stopping point. Then run `{{ALIGNFIRST}} sync`. You choose the identifier and write the request; the agent does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
|
|
29
|
+
{{/app}}
|
|
30
|
+
{{#thread}}
|
|
31
|
+
5. Before delegating the bootstrap, run `{{GUIDE}} code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{GUIDE}}`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Explicitly instruct it to use `alignfirst-setup-guide` and prepare the repository for an assistant. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. The workspace system is optional. When the project installs it, include `.local/` as a gitignored shared directory in its mechanism; otherwise the project uses `{{ALIGNDEV}} worktree` and documents its install/build/test preparation. Follow the selected stack and the host-specific guide.
|
|
32
|
+
{{/thread}}
|
|
33
|
+
{{#app}}
|
|
34
|
+
5. Before delegating the bootstrap, run `{{GUIDE}} code`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Explicitly instruct it to use `alignfirst-setup-guide` and prepare the repository for an assistant. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. The workspace system is optional. When the project installs it, include `.local/` as a gitignored shared directory in its mechanism; otherwise the project uses `{{ALIGNDEV}} worktree` and documents its install/build/test preparation. Follow the selected stack and the host-specific guide.
|
|
35
|
+
{{/app}}
|
|
26
36
|
6. Verify the project through the setup guide, run `{{ALIGNFIRST}} sync`, and make its initial commit on `main` in PROJECT_PATH. Do not ask for confirmation before committing.
|
|
27
37
|
7. When a remote destination is known from the request, environment, or host instructions, configure it when needed and push `main`. Do not ask for confirmation before pushing. When no destination is known, or the user requested a local-only project, leave the committed project local and report that no remote was configured.
|
|
28
38
|
8. After that commit and push when applicable, return to the normal working-session flow. Every subsequent branch change uses a linked project workspace.
|
|
@@ -44,7 +54,7 @@ Before any discussion:
|
|
|
44
54
|
|
|
45
55
|
### Step 2 — Check the AlignDev contract
|
|
46
56
|
|
|
47
|
-
The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Project for an Assistant": project context, usable work files outside the project's tracked tree, documentation, runtime commands, and a developer guide. The workspace system is optional. The project is prepared when DEVELOPERS_PATH exists and `{{
|
|
57
|
+
The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Project for an Assistant": project context, usable work files outside the project's tracked tree, documentation, runtime commands, and a developer guide. The workspace system is optional. The project is prepared when DEVELOPERS_PATH exists and `{{GUIDE}} work-files-setup` passes without preparation: continue with the normal working-session flow for the user's request. Otherwise, continue to Step 3.
|
|
48
58
|
|
|
49
59
|
### Step 3 — Warn and ask
|
|
50
60
|
|
|
@@ -58,10 +68,10 @@ Ask the user to approve this procedure and whether `.plans` must be shared throu
|
|
|
58
68
|
|
|
59
69
|
On approval:
|
|
60
70
|
|
|
61
|
-
1. Complete `{{
|
|
71
|
+
1. Complete `{{GUIDE}} work-files-setup` under the approved preparation, then run `{{ALIGNFIRST}} sync`. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH, write `{TICKET_DIR}A1-request.md` with the recorded request, then run `{{ALIGNFIRST}} sync`.
|
|
62
72
|
2. Create `{TICKET_ID}/alignfirst-setup` in the main worktree. This setup branch is the second main-worktree exception, next to new-project bootstrap.
|
|
63
|
-
3. Run `{{
|
|
64
|
-
4. Have the agent create a
|
|
73
|
+
3. Run `{{GUIDE}} code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and prepare the repository for an assistant, with the user's work-files repository decision and its URL. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Instruct the agent to commit and push the branch. The setup guide's rule against pushing addresses a human's laptop session, not this procedure.
|
|
74
|
+
4. Have the agent create a pull request.
|
|
65
75
|
5. End the turn on the PR link and state that work resumes once the PR is merged.
|
|
66
76
|
|
|
67
77
|
### Step 5 — After the merge
|
|
@@ -70,27 +80,32 @@ When the user reports the merge, or you observe it while checking the PR:
|
|
|
70
80
|
|
|
71
81
|
1. In the main worktree, switch back to the default branch, pull, and delete the local setup branch.
|
|
72
82
|
2. Install dependencies and build.
|
|
73
|
-
3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there (the projects guide names the repository), then run `{{ALIGNFIRST}} plans setup {{PROJECTS_ROOT}}/<clone>` from PROJECT_PATH. Otherwise keep the prepared plans. Then verify with `{{
|
|
83
|
+
3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there (the projects guide names the repository), then run `{{ALIGNFIRST}} plans setup {{PROJECTS_ROOT}}/<clone>` from PROJECT_PATH. Otherwise keep the prepared plans. Then verify with `{{GUIDE}} work-files-setup`.
|
|
74
84
|
4. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
|
|
75
85
|
5. Run the project's documented main-worktree workspace setup when it has one, otherwise its install/build/test commands.
|
|
76
|
-
6. Continue with the normal working-session flow for the original request through `{{
|
|
86
|
+
6. Continue with the normal working-session flow for the original request through `{{GUIDE}} project-workspace-setup`.
|
|
77
87
|
|
|
78
88
|
### Prepare through the companion
|
|
79
89
|
|
|
80
90
|
The preparation targets the project's companion directory. It writes nothing in the repository and creates no branch, commit or pull request.
|
|
81
91
|
|
|
82
92
|
1. Run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. It keeps an existing registration and profile selection.
|
|
83
|
-
2. Complete `{{
|
|
93
|
+
2. Complete `{{GUIDE}} work-files-setup` from PROJECT_PATH, starting at section 3: the Step 3 approval authorizes it, even when existing project plans are usable. It selects companion plans and leaves the existing work files in place without copying them.
|
|
84
94
|
3. Reread `{{ALIGNFIRST}} config --json`. Verify that `.plans` and every item to write resolve inside `companion.dir`. Missing `.alignfirst.json` and `DEVELOPERS.md` must have companion destinations. If an explicit item selection points a required write into the project, stop and resolve that selection with the user. Retain the reported companion `DEVELOPERS.md` path as DEVELOPERS_PATH.
|
|
85
95
|
4. Unless the user already said, ask whether `.plans` must be shared through a work-files repository, and for its URL if so. Wait for the answer.
|
|
86
96
|
5. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there.
|
|
87
|
-
6. Run `{{
|
|
97
|
+
6. Run `{{GUIDE}} code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and follow its procedure "Set up a project through its companion" for an assistant, with the work-files clone path when there is one.
|
|
88
98
|
7. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
|
|
89
|
-
8. Continue with the normal working-session flow for the original request through `{{
|
|
99
|
+
8. Continue with the normal working-session flow for the original request through `{{GUIDE}} project-workspace-setup`.
|
|
90
100
|
|
|
91
101
|
## Remove a project
|
|
92
102
|
|
|
103
|
+
{{#thread}}
|
|
93
104
|
Removal requires the listed PROJECT_PATH selected before the thread opened or supplied by the user.
|
|
105
|
+
{{/thread}}
|
|
106
|
+
{{#app}}
|
|
107
|
+
Removal requires the listed PROJECT_PATH supplied by the user.
|
|
108
|
+
{{/app}}
|
|
94
109
|
|
|
95
110
|
1. Run and read `{{ALIGNDEV}} guide project`, then refresh `{{ALIGNDEV}} project list --json` and resolve the listed project at PROJECT_PATH. Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH, and its companion directory when it reports one. Read DEVELOPERS_PATH, then run and read the project workspace guide it names, if any.
|
|
96
111
|
2. List every linked worktree with its exact absolute path, through the project's workspace list or, without workspace tooling, `{{ALIGNDEV}} worktree list --json` from PROJECT_PATH. Add the exact PROJECT_PATH for the main worktree. Check every worktree, the main one included, for staged, unstaged, or untracked unignored changes. A dirty worktree stops the removal before anything is unregistered or deleted, and so does a missing or locked registration until it is resolved.
|