arcane-cli 0.15.4 → 0.15.6
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/dist/assets/.arcane/governance/agent-work-queue-model.md +13 -13
- package/dist/assets/.arcane/governance/decision-documentation-standard.md +18 -18
- package/dist/assets/.arcane/governance/framework-decisions.md +71 -0
- package/dist/assets/.arcane/governance/git-conventions.md +81 -69
- package/dist/assets/.github/prompts/spell-commit-work.prompt.md +7 -0
- package/dist/assets/.github/prompts/spell-todo.prompt.md +1 -1
- package/dist/index.js +8 -1
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
|
@@ -9,7 +9,7 @@ tags: [governance, queue, agents, work-management]
|
|
|
9
9
|
|
|
10
10
|
# Agent Work Queue Model
|
|
11
11
|
|
|
12
|
-
Defines a single markdown-first queue for assigning work across businesses, while keeping Azure DevOps at Story-level visibility
|
|
12
|
+
Defines a single markdown-first queue for assigning work across businesses, while keeping Azure DevOps at Story-level visibility for human milestone tracking.
|
|
13
13
|
|
|
14
14
|
## Executive Summary
|
|
15
15
|
|
|
@@ -31,19 +31,19 @@ Defines a single markdown-first queue for assigning work across businesses, whil
|
|
|
31
31
|
|
|
32
32
|
## Canonical Fields
|
|
33
33
|
|
|
34
|
-
| Field
|
|
35
|
-
|
|
36
|
-
| Queue ID
|
|
37
|
-
| Business
|
|
38
|
-
| Repo
|
|
39
|
-
| DevOps Item
|
|
40
|
-
| Priority
|
|
34
|
+
| Field | Description |
|
|
35
|
+
| -------------- | ---------------------------------------------- |
|
|
36
|
+
| Queue ID | Unique work identifier |
|
|
37
|
+
| Business | `acme-store`, `example-app`, etc. |
|
|
38
|
+
| Repo | Target repo name |
|
|
39
|
+
| DevOps Item | Story/Task/Bug link or ID |
|
|
40
|
+
| Priority | Critical / High / Medium / Low |
|
|
41
41
|
| Assigned Agent | {AGENT_NAME}, Lafayette, Mercurio, Lince, etc. |
|
|
42
|
-
| Power Level
|
|
43
|
-
| Execution Host | Atlas, Voyager, Nimbus
|
|
44
|
-
| Approval Gate
|
|
45
|
-
| Exit Criteria
|
|
46
|
-
| Status
|
|
42
|
+
| Power Level | Apprentice/Wizard/Sorcerer/Magus/Archmage |
|
|
43
|
+
| Execution Host | Atlas, Voyager, Nimbus |
|
|
44
|
+
| Approval Gate | Required reviewer and checkpoint |
|
|
45
|
+
| Exit Criteria | Objective definition of done |
|
|
46
|
+
| Status | Backlog / Ready / In Progress / Blocked / Done |
|
|
47
47
|
|
|
48
48
|
---
|
|
49
49
|
|
|
@@ -26,10 +26,10 @@ This document defines how significant decisions are documented in this repositor
|
|
|
26
26
|
|
|
27
27
|
Arcane separates framework-level decisions from org-specific ones using two prefixes:
|
|
28
28
|
|
|
29
|
-
| Prefix | File | Scope
|
|
30
|
-
| --------- | --------------------- |
|
|
31
|
-
| `ADR-NNN` | `DECISIONS.md` | Org-specific decisions (ventures, infrastructure, runtime config, org conventions)
|
|
32
|
-
| `ARC-NNN` | `arcane/DECISIONS.md` | Arcane framework decisions (spell library, CLI, agent system, governance templates)
|
|
29
|
+
| Prefix | File | Scope |
|
|
30
|
+
| --------- | --------------------- | ----------------------------------------------------------------------------------- |
|
|
31
|
+
| `ADR-NNN` | `DECISIONS.md` | Org-specific decisions (ventures, infrastructure, runtime config, org conventions) |
|
|
32
|
+
| `ARC-NNN` | `arcane/DECISIONS.md` | Arcane framework decisions (spell library, CLI, agent system, governance templates) |
|
|
33
33
|
|
|
34
34
|
**Rules:**
|
|
35
35
|
|
|
@@ -99,7 +99,7 @@ This check was added after [[governance/rcas/RCA-001-naming-collision|RCA-001]]
|
|
|
99
99
|
**Create a companion doc if:**
|
|
100
100
|
|
|
101
101
|
- Decision justification exceeds 5 bullets in "Reasoning" section
|
|
102
|
-
- Multiple ADRs share a common theme (e.g., authentication
|
|
102
|
+
- Multiple ADRs share a common theme (e.g., several authentication decisions belong in one authentication strategy)
|
|
103
103
|
- Implementation has significant gotchas or edge cases
|
|
104
104
|
- Decision has ongoing review/maintenance requirements (quarterly audits, version compatibility)
|
|
105
105
|
- You anticipate "why did we do this?" questions from future team members or external auditors
|
|
@@ -115,13 +115,13 @@ This check was added after [[governance/rcas/RCA-001-naming-collision|RCA-001]]
|
|
|
115
115
|
|
|
116
116
|
Use existing folder structure; **do not create `deep-dives/` or `DECISIONS-details/` folders**.
|
|
117
117
|
|
|
118
|
-
| Decision Theme | Location | Example
|
|
119
|
-
| ------------------------------------ | ------------------ |
|
|
120
|
-
| Authentication, credentials, keys | `security/` | [security/authentication-strategy.md](../security/authentication-strategy.md)
|
|
121
|
-
| Hardware, OS, dual-boot | `infrastructure/` | [infrastructure/compute-architecture.md](../infrastructure/compute-architecture.md)
|
|
122
|
-
| Agent runtime config, agent policies | `agents/` | [agents/architecture-decisions.md](../agents/architecture-decisions.md)
|
|
123
|
-
| Git, naming, documentation standards | `governance/` | This file
|
|
124
|
-
| Business-specific operations | `ventures/{name}/` | `ventures/acme-store/DECISIONS.md`, `ventures/example-app/operations-model.md`
|
|
118
|
+
| Decision Theme | Location | Example |
|
|
119
|
+
| ------------------------------------ | ------------------ | ----------------------------------------------------------------------------------- |
|
|
120
|
+
| Authentication, credentials, keys | `security/` | [security/authentication-strategy.md](../security/authentication-strategy.md) |
|
|
121
|
+
| Hardware, OS, dual-boot | `infrastructure/` | [infrastructure/compute-architecture.md](../infrastructure/compute-architecture.md) |
|
|
122
|
+
| Agent runtime config, agent policies | `agents/` | [agents/architecture-decisions.md](../agents/architecture-decisions.md) |
|
|
123
|
+
| Git, naming, documentation standards | `governance/` | This file |
|
|
124
|
+
| Business-specific operations | `ventures/{name}/` | `ventures/acme-store/DECISIONS.md`, `ventures/example-app/operations-model.md` |
|
|
125
125
|
|
|
126
126
|
**Rationale:** Keeps security knowledge with security docs, infrastructure with infrastructure, etc. Easier to discover via folder browsing.
|
|
127
127
|
|
|
@@ -131,7 +131,7 @@ Use existing folder structure; **do not create `deep-dives/` or `DECISIONS-detai
|
|
|
131
131
|
|
|
132
132
|
- ✅ `security/authentication-strategy.md` — covers SSH, PATs, API keys, tokens (multiple ADRs)
|
|
133
133
|
- ✅ `infrastructure/compute-architecture.md` — covers dual-boot, Ubuntu choice, hardware sizing
|
|
134
|
-
- ❌ `security/ADR-
|
|
134
|
+
- ❌ `security/ADR-NNN-deep-dive.md` — Forces 1:1 mapping, harder to group related decisions
|
|
135
135
|
|
|
136
136
|
**Filename format:** `{topic-slug}.md` (lowercase, hyphen-separated)
|
|
137
137
|
|
|
@@ -214,7 +214,7 @@ Add this section **after Reasoning, before Rejected alternatives** in the ADR:
|
|
|
214
214
|
**Deep dive:** [[security/authentication-strategy|Authentication Strategy]]
|
|
215
215
|
```
|
|
216
216
|
|
|
217
|
-
**Example from ADR
|
|
217
|
+
**Example from an authentication ADR:**
|
|
218
218
|
|
|
219
219
|
```markdown
|
|
220
220
|
**Reasoning:**
|
|
@@ -238,12 +238,12 @@ Create "Related ADRs" section at the top of every companion doc:
|
|
|
238
238
|
```markdown
|
|
239
239
|
## Related ADRs
|
|
240
240
|
|
|
241
|
-
- [[DECISIONS#ADR-
|
|
242
|
-
- [[DECISIONS#ADR-
|
|
243
|
-
- [[DECISIONS#ADR-
|
|
241
|
+
- [[DECISIONS#ADR-NNN|Runtime Gateway Security decision]]
|
|
242
|
+
- [[DECISIONS#ADR-NNN|Inter-Machine Communication decision]]
|
|
243
|
+
- [[DECISIONS#ADR-NNN|Git SSH Authentication decision]]
|
|
244
244
|
```
|
|
245
245
|
|
|
246
|
-
**Rationale:** Creates bidirectional graph edges in Obsidian visualization. Clicking ADR
|
|
246
|
+
**Rationale:** Creates bidirectional graph edges in Obsidian visualization. Clicking an ADR shows its authentication strategy companion; the companion links back to each related ADR.
|
|
247
247
|
|
|
248
248
|
---
|
|
249
249
|
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Legacy Framework Decision Reference
|
|
3
|
+
audience: both
|
|
4
|
+
status: active
|
|
5
|
+
distributable: true
|
|
6
|
+
tags: [decisions, adr, framework, references]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Legacy Framework Decision Reference
|
|
10
|
+
|
|
11
|
+
Arcane framework decisions now use the `ARC-NNN` sequence. The entries below preserve the legacy `ADR-NNN` identifiers still cited by distributed governance and spells so every installed citation resolves offline. Consumer repository decisions remain in the root `DECISIONS.md` and use their own local sequence.
|
|
12
|
+
|
|
13
|
+
## ADR-002 — Documentation in Markdown and Git
|
|
14
|
+
|
|
15
|
+
Keep operational documentation in reviewable, version-controlled Markdown alongside the work it governs.
|
|
16
|
+
|
|
17
|
+
## ADR-011 — Troubleshooting Standard
|
|
18
|
+
|
|
19
|
+
Troubleshooting guidance uses Symptom, Cause, Fix, Verify, and Prevention sections so remediation is reproducible.
|
|
20
|
+
|
|
21
|
+
## ADR-019 — Spell Prompt Naming
|
|
22
|
+
|
|
23
|
+
Arcane workflow prompts use the `spell-` prefix to make their purpose and invocation surface explicit.
|
|
24
|
+
|
|
25
|
+
## ADR-028 — Agent Git Attribution Model
|
|
26
|
+
|
|
27
|
+
The content producer is the commit author, the approving operator is the committer, and agent-authored commits carry attribution trailers.
|
|
28
|
+
|
|
29
|
+
## ADR-029 — Canonical Commit Metadata Schema
|
|
30
|
+
|
|
31
|
+
Agent commits use stable `Agent`, `Model`, and `Provider` trailers, with optional role, task, channel, and approval metadata.
|
|
32
|
+
|
|
33
|
+
## ADR-031 — Agent Role Consolidation
|
|
34
|
+
|
|
35
|
+
Agent identities represent durable roles rather than framework-specific technology stacks.
|
|
36
|
+
|
|
37
|
+
## ADR-032 — Context-Dependent Agent Power Levels
|
|
38
|
+
|
|
39
|
+
Agent autonomy is assigned per agent and repository through the Spectator-to-Archmage ladder.
|
|
40
|
+
|
|
41
|
+
## ADR-034 — Actionable Recommendation Guardrails
|
|
42
|
+
|
|
43
|
+
Recommendations involving cost, accounts, subscriptions, or irreversible action require disclosure, current verification, alternatives, and proportionate approval.
|
|
44
|
+
|
|
45
|
+
## ADR-048 — Code Versus Docs Branch Policy
|
|
46
|
+
|
|
47
|
+
Code repositories use protected integration branches and reviewed PRs. A genuinely local-only documentation repository may integrate a reviewed docs change with a local fast-forward when no remote PR path exists.
|
|
48
|
+
|
|
49
|
+
## ADR-049 — Spell Loop
|
|
50
|
+
|
|
51
|
+
Arcane's lifecycle is plan, architect, implement, test, review, and ship, with session and operational spells supporting the loop.
|
|
52
|
+
|
|
53
|
+
## ADR-050 — Testing Standards
|
|
54
|
+
|
|
55
|
+
Projects select stack-appropriate test tooling and enforce coverage and critical-path evidence before shipping.
|
|
56
|
+
|
|
57
|
+
## ADR-051 — Infrastructure Agent Ownership
|
|
58
|
+
|
|
59
|
+
The infrastructure role owns CI/CD, deployment automation, and platform operations while remaining subject to repository authority gates.
|
|
60
|
+
|
|
61
|
+
## ADR-052 — Product Excellence Standards
|
|
62
|
+
|
|
63
|
+
PRD enhancement uses explicit quality dimensions and profile-dependent Bronze, Silver, and Gold targets.
|
|
64
|
+
|
|
65
|
+
## ADR-061 — Arcane Framework Identity
|
|
66
|
+
|
|
67
|
+
Arcane is a four-layer methodology composed of Spells, Governance, Agents, and the CLI.
|
|
68
|
+
|
|
69
|
+
## ADR-068 — Root Cause Analysis Standard
|
|
70
|
+
|
|
71
|
+
Material incidents receive structured root cause analysis with evidence, corrective actions, prevention, and follow-up ownership.
|
|
@@ -36,18 +36,18 @@ type(scope): short description
|
|
|
36
36
|
|
|
37
37
|
### Commit Types
|
|
38
38
|
|
|
39
|
-
| Type | When to Use | Example
|
|
40
|
-
| ---------- | ----------------------------------------------- |
|
|
41
|
-
| `feat` | New feature or capability | `feat(prompts): add spell-commit-work for checkpointing`
|
|
42
|
-
| `fix` | Bug fix | `fix(auth): restore token validation after refactor`
|
|
43
|
-
| `docs` | Documentation only | `docs(decisions): add table of contents to DECISIONS.md`
|
|
44
|
-
| `refactor` | Code/structure change, no behavior change | `refactor(playbooks): reorganize setup steps`
|
|
45
|
-
| `chore` | Maintenance, deps, tooling, cleanup | `chore(deps): bump <dependency> to <version>`
|
|
46
|
-
| `test` | Adding or fixing tests | `test(security): add token-expiry test`
|
|
47
|
-
| `perf` | Performance improvements | `perf(api): reduce cold-start latency`
|
|
48
|
-
| `ci` | CI/CD pipeline changes | `ci(azure): add DevOps pipeline for repo sync`
|
|
49
|
-
| `style` | Code formatting, whitespace (rare in this repo) | `style(markdown): fix inconsistent heading levels`
|
|
50
|
-
| `revert` | Revert a previous commit | `revert: undo feat(prompts): add spell-commit-work`
|
|
39
|
+
| Type | When to Use | Example |
|
|
40
|
+
| ---------- | ----------------------------------------------- | -------------------------------------------------------- |
|
|
41
|
+
| `feat` | New feature or capability | `feat(prompts): add spell-commit-work for checkpointing` |
|
|
42
|
+
| `fix` | Bug fix | `fix(auth): restore token validation after refactor` |
|
|
43
|
+
| `docs` | Documentation only | `docs(decisions): add table of contents to DECISIONS.md` |
|
|
44
|
+
| `refactor` | Code/structure change, no behavior change | `refactor(playbooks): reorganize setup steps` |
|
|
45
|
+
| `chore` | Maintenance, deps, tooling, cleanup | `chore(deps): bump <dependency> to <version>` |
|
|
46
|
+
| `test` | Adding or fixing tests | `test(security): add token-expiry test` |
|
|
47
|
+
| `perf` | Performance improvements | `perf(api): reduce cold-start latency` |
|
|
48
|
+
| `ci` | CI/CD pipeline changes | `ci(azure): add DevOps pipeline for repo sync` |
|
|
49
|
+
| `style` | Code formatting, whitespace (rare in this repo) | `style(markdown): fix inconsistent heading levels` |
|
|
50
|
+
| `revert` | Revert a previous commit | `revert: undo feat(prompts): add spell-commit-work` |
|
|
51
51
|
|
|
52
52
|
### Scopes
|
|
53
53
|
|
|
@@ -167,7 +167,7 @@ Use `git add -p` or selective staging to separate unrelated changes that were ed
|
|
|
167
167
|
```bash
|
|
168
168
|
# Stage only the files related to one logical change
|
|
169
169
|
git add governance/new-standard.md DECISIONS.md CLAUDE.md
|
|
170
|
-
git commit -m "docs(governance): add new-standard with ADR-
|
|
170
|
+
git commit -m "docs(governance): add new-standard with ADR-NNN"
|
|
171
171
|
|
|
172
172
|
# Then stage the unrelated fix
|
|
173
173
|
git add README.md
|
|
@@ -303,10 +303,10 @@ When working across machines, topic branches are the coordination mechanism:
|
|
|
303
303
|
|
|
304
304
|
### Merge Strategy by Repo Risk
|
|
305
305
|
|
|
306
|
-
| Repo Type | Examples
|
|
307
|
-
| -------------- |
|
|
308
|
-
| **Docs repos** | docs hub, prototypes
|
|
309
|
-
| **Code repos** | application, API, storefront repos
|
|
306
|
+
| Repo Type | Examples | Merge Method | PR Required? |
|
|
307
|
+
| -------------- | ---------------------------------- | ------------ | ------------ |
|
|
308
|
+
| **Docs repos** | docs hub, prototypes | PR | Yes |
|
|
309
|
+
| **Code repos** | application, API, storefront repos | PR | Yes |
|
|
310
310
|
|
|
311
311
|
- **All repos have main branch protection.** Direct pushes to main are rejected. All changes must go through a PR.
|
|
312
312
|
|
|
@@ -319,22 +319,22 @@ When completing a PR in Azure DevOps, allow only these merge strategies by defau
|
|
|
319
319
|
|
|
320
320
|
Do **not** use Squash commit.
|
|
321
321
|
|
|
322
|
-
| Merge Type | Use? | Why
|
|
323
|
-
| --------------------------- | ------- |
|
|
324
|
-
| **Rebase and fast-forward** | **Yes** | Preserves linear history while keeping individual commits and attribution trailers intact.
|
|
325
|
-
| **Merge (no fast forward)** | **Yes** | Preserves full branch context and review traceability where explicit merge commits are preferred.
|
|
326
|
-
| Squash commit | **No** | Collapses commit history and breaks per-commit attribution/analytics and granular rollback.
|
|
327
|
-
| Semi-linear merge | No | Adds unnecessary merge commits on top of rebased commits; avoid by default.
|
|
322
|
+
| Merge Type | Use? | Why |
|
|
323
|
+
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
|
|
324
|
+
| **Rebase and fast-forward** | **Yes** | Preserves linear history while keeping individual commits and attribution trailers intact. |
|
|
325
|
+
| **Merge (no fast forward)** | **Yes** | Preserves full branch context and review traceability where explicit merge commits are preferred. |
|
|
326
|
+
| Squash commit | **No** | Collapses commit history and breaks per-commit attribution/analytics and granular rollback. |
|
|
327
|
+
| Semi-linear merge | No | Adds unnecessary merge commits on top of rebased commits; avoid by default. |
|
|
328
328
|
|
|
329
329
|
### Commit Governance
|
|
330
330
|
|
|
331
331
|
Commit execution rights depend on the interaction context:
|
|
332
332
|
|
|
333
|
-
| Context | Commit Behavior
|
|
334
|
-
| ----------------------------------------------------------------- |
|
|
335
|
-
| **Interactive session** (Copilot, Claude in VS Code, Claude Code) | **Must ask human** before committing. Stage changes, present proposed message, wait for approval.
|
|
336
|
-
| **Autonomous agent** at Magus+ power level
|
|
337
|
-
| **Autonomous agent** below Magus
|
|
333
|
+
| Context | Commit Behavior | Rationale |
|
|
334
|
+
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
|
335
|
+
| **Interactive session** (Copilot, Claude in VS Code, Claude Code) | **Must ask human** before committing. Stage changes, present proposed message, wait for approval. | Human is actively collaborating; commits are a shared decision. |
|
|
336
|
+
| **Autonomous agent** at Magus+ power level | May self-commit and self-merge within approved scope (per your power-level policy). Must use proper author/trailers. | Agent is operating independently with delegated authority. |
|
|
337
|
+
| **Autonomous agent** below Magus | Must commit to topic branch and queue merge for human review. | Insufficient autonomy level for unsupervised merges to main. |
|
|
338
338
|
|
|
339
339
|
**Interactive session rule applies to ALL interactive tools, regardless of agent identity.** Even a high-power-level agent cannot auto-commit when operating through an interactive editor session — the human is present and must approve.
|
|
340
340
|
|
|
@@ -403,19 +403,19 @@ git push origin --delete <branch> # delete remote branch (safety net —
|
|
|
403
403
|
|
|
404
404
|
**Known issues:**
|
|
405
405
|
|
|
406
|
-
| Issue
|
|
407
|
-
|
|
|
408
|
-
| Reviewer already assigned
|
|
409
|
-
| `az repos pr set-vote` succeeds but approval still blocked
|
|
410
|
-
| MCP `vote_pull_request` returns "Success" but vote stays 0
|
|
411
|
-
| `az rest --body '{"vote":10}'` fails
|
|
412
|
-
| `az repos pr update --status completed` fails with policy error
|
|
413
|
-
| MCP `create_pull_request` returns no data
|
|
414
|
-
| `gh pr create` not found
|
|
415
|
-
| `creatorVoteCounts` is false on branch policy
|
|
416
|
-
| `az repos pr update --status completed` returns `status: active` without error | PR silently not merged
|
|
417
|
-
| `git branch -d <branch>` fails after merge
|
|
418
|
-
| `git push origin --delete <branch>` fails with missing ref
|
|
406
|
+
| Issue | Symptom | Fix |
|
|
407
|
+
| ------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------- |
|
|
408
|
+
| Reviewer already assigned | `reviewer add` returns already exists | Treat as idempotent success and continue |
|
|
409
|
+
| `az repos pr set-vote` succeeds but approval still blocked | Policy requires additional approver | Confirm vote state, then request second human approval |
|
|
410
|
+
| MCP `vote_pull_request` returns "Success" but vote stays 0 | `reviewer list` shows `vote: 0` | Use `Invoke-RestMethod` step 5 above |
|
|
411
|
+
| `az rest --body '{"vote":10}'` fails | Shell parsing error on Windows | Use `Invoke-RestMethod` |
|
|
412
|
+
| `az repos pr update --status completed` fails with policy error | "Needs 1 approval" | Verify `vote: 10` first, then retry |
|
|
413
|
+
| MCP `create_pull_request` returns no data | No PR ID/URL in response | Fall back to `az repos pr create` |
|
|
414
|
+
| `gh pr create` not found | `gh` CLI not installed | Use `az repos pr create` |
|
|
415
|
+
| `creatorVoteCounts` is false on branch policy | Vote registers but PR still blocked | A second human must approve via ADO web UI |
|
|
416
|
+
| `az repos pr update --status completed` returns `status: active` without error | PR silently not merged | Add `--squash false` to the command; the flag triggers the merge path correctly |
|
|
417
|
+
| `git branch -d <branch>` fails after merge | Branch is attached to a worktree | Skip local delete; run remote delete + prune |
|
|
418
|
+
| `git push origin --delete <branch>` fails with missing ref | Branch already deleted remotely | Treat as non-fatal and continue |
|
|
419
419
|
|
|
420
420
|
### Branch Lifecycle
|
|
421
421
|
|
|
@@ -482,14 +482,14 @@ See also: [Agent Workflow — Sync with main before opening a PR](#agent-workflo
|
|
|
482
482
|
|
|
483
483
|
### PR Requirements
|
|
484
484
|
|
|
485
|
-
| Requirement | Details
|
|
486
|
-
| ------------------ |
|
|
487
|
-
| **Work item link** | Optional. Linking is encouraged for traceability but enforce it only if your branch policy requires it.
|
|
488
|
-
| **Title format** | Conventional Commits format: `type(scope): description`
|
|
489
|
-
| **Description** | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable
|
|
485
|
+
| Requirement | Details |
|
|
486
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
487
|
+
| **Work item link** | Optional. Linking is encouraged for traceability but enforce it only if your branch policy requires it. |
|
|
488
|
+
| **Title format** | Conventional Commits format: `type(scope): description` |
|
|
489
|
+
| **Description** | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable |
|
|
490
490
|
| **Pre-PR sync** | **Mandatory rebase on latest `origin/<target>` before pushing.** See [🛑 Agent-mandatory pre-PR guard](#-agent-mandatory-pre-pr-guard) above — this applies even when opening PRs via raw `az repos pr create` / `gh pr create` / MCP tools. |
|
|
491
|
-
| **Branch cleanup** | After merge, delete the source branch (local and remote).
|
|
492
|
-
| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`.
|
|
491
|
+
| **Branch cleanup** | After merge, delete the source branch (local and remote). |
|
|
492
|
+
| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`. |
|
|
493
493
|
|
|
494
494
|
### Agent PR Workflow
|
|
495
495
|
|
|
@@ -522,6 +522,7 @@ Every commit must clearly identify **who produced the content** and **who approv
|
|
|
522
522
|
- If **you** wrote the content: don't override author. Your global Git config is used.
|
|
523
523
|
- If an **agent** produced the content: use `--author` to set the agent's identity.
|
|
524
524
|
- If an **interactive AI tool** (Copilot, Claude in VS Code) produced the content: use the tool-level identity.
|
|
525
|
+
- If the content is an **Arcane vendored scaffold or managed update**: do not invent a vendor email identity and do not use an agent author. Keep the operator's Git identity and record package provenance with `Vendor: arcane-cli` plus a programmatically derived `Vendor-Version` when available. Split mixed vendor/operator changes first.
|
|
525
526
|
|
|
526
527
|
### Agent Email Convention
|
|
527
528
|
|
|
@@ -531,14 +532,14 @@ Give every agent/tool a stable email under a domain you control. Most hosts trea
|
|
|
531
532
|
|
|
532
533
|
Maintain a registry of the identities you use, for example:
|
|
533
534
|
|
|
534
|
-
| Identity | Email
|
|
535
|
-
| --------------- |
|
|
536
|
-
| {OPERATOR_NAME} | `{OPERATOR_EMAIL}`
|
|
537
|
-
| {AGENT_NAME} | `{AGENT_EMAIL}`
|
|
538
|
-
| Merlin
|
|
539
|
-
| Lafayette
|
|
540
|
-
| Copilot | `copilot@{OPERATOR_DOMAIN}`
|
|
541
|
-
| Claude | `claude@{OPERATOR_DOMAIN}`
|
|
535
|
+
| Identity | Email | Type | Role |
|
|
536
|
+
| --------------- | ----------------------------- | ---------------- | -------------------------- |
|
|
537
|
+
| {OPERATOR_NAME} | `{OPERATOR_EMAIL}` | Human (owner) | — |
|
|
538
|
+
| {AGENT_NAME} | `{AGENT_EMAIL}` | Autonomous agent | Product Operations Manager |
|
|
539
|
+
| Merlin | `merlin@{OPERATOR_DOMAIN}` | Autonomous agent | CTO / Architecture Lead |
|
|
540
|
+
| Lafayette | `lafayette@{OPERATOR_DOMAIN}` | Autonomous agent | Full-Stack Developer |
|
|
541
|
+
| Copilot | `copilot@{OPERATOR_DOMAIN}` | GitHub Copilot | Tool |
|
|
542
|
+
| Claude | `claude@{OPERATOR_DOMAIN}` | Claude Code | Tool |
|
|
542
543
|
|
|
543
544
|
New agents are registered during onboarding.
|
|
544
545
|
|
|
@@ -546,19 +547,30 @@ New agents are registered during onboarding.
|
|
|
546
547
|
|
|
547
548
|
Agent-authored commits MUST include trailers in the commit message footer. Human commits MAY include them.
|
|
548
549
|
|
|
549
|
-
| Trailer | Required | Example
|
|
550
|
-
| -------------- | ----------- |
|
|
551
|
-
| `Agent` | Yes | `kellar`, `copilot`, `claude`
|
|
552
|
-
| `Model` | Yes | `claude-opus-4-20250918`, `gpt-4o`
|
|
553
|
-
| `Provider` | Yes | `anthropic`, `openai`
|
|
554
|
-
| `Role` | Recommended | `product-ops`, `developer`, `cto`
|
|
555
|
-
| `Task-Type` | Optional | `docs`, `code`, `review`, `marketing`
|
|
556
|
-
| `Approval` | Optional | `interactive`, `batch`, `post-review`
|
|
557
|
-
| `Channel` | Optional | `chat`, `cli`, `editor`
|
|
558
|
-
| `Risk-Class` | Optional | `low`, `medium`, `high`
|
|
559
|
-
| `Request-ID` | Optional | `req-001`
|
|
560
|
-
| `Session` | Optional | `session-01`
|
|
561
|
-
| `Rollback-Ref` | Optional | path or commit to the pre-change state
|
|
550
|
+
| Trailer | Required | Example |
|
|
551
|
+
| -------------- | ----------- | -------------------------------------- |
|
|
552
|
+
| `Agent` | Yes | `kellar`, `copilot`, `claude` |
|
|
553
|
+
| `Model` | Yes | `claude-opus-4-20250918`, `gpt-4o` |
|
|
554
|
+
| `Provider` | Yes | `anthropic`, `openai` |
|
|
555
|
+
| `Role` | Recommended | `product-ops`, `developer`, `cto` |
|
|
556
|
+
| `Task-Type` | Optional | `docs`, `code`, `review`, `marketing` |
|
|
557
|
+
| `Approval` | Optional | `interactive`, `batch`, `post-review` |
|
|
558
|
+
| `Channel` | Optional | `chat`, `cli`, `editor` |
|
|
559
|
+
| `Risk-Class` | Optional | `low`, `medium`, `high` |
|
|
560
|
+
| `Request-ID` | Optional | `req-001` |
|
|
561
|
+
| `Session` | Optional | `session-01` |
|
|
562
|
+
| `Rollback-Ref` | Optional | path or commit to the pre-change state |
|
|
563
|
+
|
|
564
|
+
### Vendored Framework Trailers
|
|
565
|
+
|
|
566
|
+
Vendored scaffold/update commits use these provenance trailers instead of an invented Arcane author identity:
|
|
567
|
+
|
|
568
|
+
| Trailer | Requirement | Value |
|
|
569
|
+
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
|
|
570
|
+
| `Vendor` | Required | `arcane-cli` |
|
|
571
|
+
| `Vendor-Version` | Conditional | Output of `arcane --version` / `spell --version`, whose value is read from the installed CLI's `package.json` |
|
|
572
|
+
|
|
573
|
+
Never type or infer `Vendor-Version`. If the installed CLI cannot be resolved programmatically, omit the version trailer and disclose incomplete provenance rather than guessing.
|
|
562
574
|
|
|
563
575
|
### Complete Examples
|
|
564
576
|
|
|
@@ -54,6 +54,10 @@ Workflow:
|
|
|
54
54
|
- **Invariant: one commit has exactly one author.** Changes spanning authors must be split into separate commits.
|
|
55
55
|
- Partition changed files by author first. Step 4 then groups by concern within each author partition; concern grouping must never recombine authors.
|
|
56
56
|
- **Human wrote it:** no `--author` override needed (uses global Git config)
|
|
57
|
+
- **Arcane vendored scaffold/update:** no `--author` override; the operator's Git identity records the repository action. Add `Vendor: arcane-cli` and, when derivable, `Vendor-Version: <version>` trailers.
|
|
58
|
+
- Derive the version at commit time by running `arcane --version` (or the resolved `spell --version` alias). The CLI reads its installed package's `package.json`; never type the version, copy it from memory, or infer it from the repository manifest.
|
|
59
|
+
- If the installed CLI version cannot be read programmatically, omit `Vendor-Version` and report that provenance is incomplete. Never guess.
|
|
60
|
+
- A batch mixing vendored files with human- or agent-authored changes spans provenance authors and must be split before concern grouping.
|
|
57
61
|
- **AI agent/tool produced it:** use `--author` with the agent's registered identity:
|
|
58
62
|
- Roster agent: `--author="{AGENT_NAME} <{AGENT_EMAIL}>"` — resolve `{AGENT_NAME}` / `{AGENT_EMAIL}` from the active agent config (see [[agent-policies]] / [[naming-conventions]]); ask if unset.
|
|
59
63
|
- Generic CLI/IDE tool: `--author="{TOOL_NAME} <{TOOL_NAME_LOWER}@{OPERATOR_DOMAIN}>"` — resolve `{TOOL_NAME}` from the channel in use and `{OPERATOR_DOMAIN}` from `.arcane.json`; ask if unset.
|
|
@@ -114,6 +118,8 @@ Workflow:
|
|
|
114
118
|
Agent: [lowercase-persona or tool name]
|
|
115
119
|
Model: [model identifier, e.g., claude-opus-4-20250918]
|
|
116
120
|
Provider: [anthropic or openai]
|
|
121
|
+
Vendor: [arcane-cli, for vendored scaffold/update commits]
|
|
122
|
+
Vendor-Version: [programmatically derived installed package version, when available]
|
|
117
123
|
Role: [agent role slug, if applicable]
|
|
118
124
|
Task-Type: [docs, code, review, marketing, infra]
|
|
119
125
|
Channel: [vscode, cli, chat]
|
|
@@ -126,6 +132,7 @@ Workflow:
|
|
|
126
132
|
- Reference ADRs if applicable (e.g., "Implements ADR-028")
|
|
127
133
|
- Trailers go after a blank line following the body (standard Git footer position)
|
|
128
134
|
- Required trailers for agent commits: `Agent`, `Model`, `Provider`
|
|
135
|
+
- Required trailer for Arcane-vendored commits: `Vendor: arcane-cli`; include `Vendor-Version` only when derived from the installed CLI at commit time
|
|
129
136
|
- Human-authored commits: trailers are optional
|
|
130
137
|
|
|
131
138
|
8. **Gate and execute the commit:**
|
|
@@ -67,7 +67,7 @@ Expand the idea into one or more concrete TODO items. Each item must:
|
|
|
67
67
|
|
|
68
68
|
If the idea naturally decomposes into multiple sub-items (e.g., "build dashboard" → design, implement, deploy, document), list them individually — do not bundle vague compound items.
|
|
69
69
|
|
|
70
|
-
If the idea is an `adr-candidate`, also draft a one-sentence ADR title suggestion (e.g., `ADR-
|
|
70
|
+
If the idea is an `adr-candidate`, also draft a one-sentence ADR title suggestion (e.g., `ADR-NNN: Use GitHub Actions for CI instead of Azure Pipelines`).
|
|
71
71
|
|
|
72
72
|
## Step 3 — Route to the Right Document
|
|
73
73
|
|
package/dist/index.js
CHANGED
|
@@ -134,7 +134,7 @@ var PROFILE_CONFIGS = [
|
|
|
134
134
|
id: "lite",
|
|
135
135
|
displayName: "Essentials",
|
|
136
136
|
description: "Spells + core governance \u2014 fast start",
|
|
137
|
-
components: ["spell-prompts", "claude-commands", "agent-output-instructions", "git-conventions", "testing-standards", "session-continuity"]
|
|
137
|
+
components: ["spell-prompts", "claude-commands", "agent-output-instructions", "git-conventions", "testing-standards", "framework-decisions", "session-continuity"]
|
|
138
138
|
},
|
|
139
139
|
{
|
|
140
140
|
id: "methodology",
|
|
@@ -146,6 +146,7 @@ var PROFILE_CONFIGS = [
|
|
|
146
146
|
"agent-output-instructions",
|
|
147
147
|
"git-conventions",
|
|
148
148
|
"testing-standards",
|
|
149
|
+
"framework-decisions",
|
|
149
150
|
"session-continuity",
|
|
150
151
|
"decision-documentation-standard",
|
|
151
152
|
"agent-work-queue-model",
|
|
@@ -161,6 +162,7 @@ var PROFILE_CONFIGS = [
|
|
|
161
162
|
"agent-output-instructions",
|
|
162
163
|
"git-conventions",
|
|
163
164
|
"testing-standards",
|
|
165
|
+
"framework-decisions",
|
|
164
166
|
"decision-documentation-standard",
|
|
165
167
|
"agent-work-queue-model",
|
|
166
168
|
"naming-conventions",
|
|
@@ -203,6 +205,11 @@ var COMPONENTS = [
|
|
|
203
205
|
description: "Testing framework selection, coverage thresholds, and CI gates",
|
|
204
206
|
files: [".arcane/governance/testing-standards.md"]
|
|
205
207
|
},
|
|
208
|
+
{
|
|
209
|
+
name: "framework-decisions",
|
|
210
|
+
description: "Offline reference for legacy framework ADR citations",
|
|
211
|
+
files: [".arcane/governance/framework-decisions.md"]
|
|
212
|
+
},
|
|
206
213
|
{
|
|
207
214
|
name: "decision-documentation-standard",
|
|
208
215
|
description: "ADR format and decision-logging conventions",
|