@open-agent-toolkit/cli 0.3.17 → 0.3.19

package/dist/commands/shared/agents-md-lock.js

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, unlink } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { relative } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+/** Specific advisory serialization for cooperating AGENTS.md appenders. */
+export async function acquireAgentsMdAppendLock(repoRoot, targetPath) {
+    const lockPath = `${targetPath}.oat-guidance.lock`;
+    const location = relative(repoRoot, lockPath);
+    const recovery = `Check the recorded host/PID and remove ${location} manually only after verifying its owner is gone, then rerun.`;
+    const token = randomUUID();
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+        let handle;
+        try {
+            handle = await open(lockPath, constants.O_RDWR |
+                constants.O_CREAT |
+                constants.O_EXCL |
+                constants.O_NOFOLLOW |
+                constants.O_NONBLOCK, 0o600);
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                !('code' in error) ||
+                error.code !== 'EEXIST') {
+                throw new Error(`AGENTS.md append lock could not be acquired. ${recovery}`, { cause: error });
+            }
+            // Never steal, truncate, or follow a contender's lock, including stale locks.
+            let reader;
+            try {
+                reader = await open(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                const stat = await reader.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 4096)
+                    throw new Error('Unsafe lock', { cause: error });
+                const content = await reader.readFile('utf8');
+                if (content === '' && attempt < 39) {
+                    await delay(25);
+                    continue;
+                }
+                const owner = JSON.parse(content);
+                if (typeof owner.token !== 'string' ||
+                    typeof owner.host !== 'string' ||
+                    !Number.isSafeInteger(owner.pid) ||
+                    owner.pid <= 0)
+                    throw new Error('Malformed lock', { cause: error });
+            }
+            catch (inspectionError) {
+                if (inspectionError instanceof Error &&
+                    'code' in inspectionError &&
+                    inspectionError.code === 'ENOENT')
+                    continue;
+                throw new Error(`AGENTS.md append lock is unsafe or malformed. ${recovery}`, { cause: inspectionError });
+            }
+            finally {
+                await reader?.close();
+            }
+            if (attempt < 39)
+                await delay(25);
+            continue;
+        }
+        const identity = await handle.stat();
+        const bytes = JSON.stringify({ token, host: hostname(), pid: process.pid });
+        let releasing;
+        let interrupted;
+        const onInt = () => {
+            interrupted = 'SIGINT';
+        };
+        const onTerm = () => {
+            interrupted = 'SIGTERM';
+        };
+        const release = () => {
+            releasing ??= (async () => {
+                process.removeListener('SIGINT', onInt);
+                process.removeListener('SIGTERM', onTerm);
+                try {
+                    const current = await lstat(lockPath);
+                    if (current.isFile() &&
+                        current.nlink === 1 &&
+                        current.dev === identity.dev &&
+                        current.ino === identity.ino &&
+                        current.size === Buffer.byteLength(bytes) &&
+                        (await readOwnedBytes()) === bytes) {
+                        const verified = await lstat(lockPath);
+                        if (verified.dev === identity.dev && verified.ino === identity.ino)
+                            await unlink(lockPath);
+                    }
+                }
+                catch (error) {
+                    if (!(error instanceof Error) ||
+                        !('code' in error) ||
+                        error.code !== 'ENOENT')
+                        throw error;
+                }
+                finally {
+                    await handle.close();
+                    if (interrupted)
+                        process.kill(process.pid, interrupted);
+                }
+            })().catch((error) => {
+                throw new Error(`AGENTS.md append lock cleanup failed; guidance may already have been written. ${recovery}`, { cause: error });
+            });
+            return releasing;
+        };
+        const readOwnedBytes = async () => {
+            const buffer = Buffer.alloc(Buffer.byteLength(bytes));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            return buffer.subarray(0, bytesRead).toString('utf8');
+        };
+        try {
+            await handle.writeFile(bytes);
+        }
+        catch (error) {
+            // Initialization failed before returning ownership; remove only this inode.
+            try {
+                const current = await lstat(lockPath);
+                if (current.dev === identity.dev && current.ino === identity.ino)
+                    await unlink(lockPath);
+            }
+            finally {
+                await handle.close();
+            }
+            throw error;
+        }
+        // Cleanup runs after the critical section and on catchable termination.
+        process.once('SIGINT', onInt);
+        process.once('SIGTERM', onTerm);
+        return release;
+    }
+    throw new Error(`AGENTS.md append lock is held by another writer. ${recovery}`);
+}

package/dist/commands/shared/agents-md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/agents-md.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/agents-md.ts"],"names":[],"mappings":"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"}

package/dist/commands/shared/agents-md.js

@@ -1,6 +1,7 @@
 import { constants } from 'node:fs';
 import { lstat, open, readFile, readlink, realpath, writeFile, } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { acquireAgentsMdAppendLock } from './agents-md-lock.js';
 const defaultFileSystem = {
     lstat,
     open,
@@ -496,7 +497,7 @@ function classifySections(plan, desired, content, removeSectionKeys, appendRefus
     };
 }
 /** Inspect current bytes and identity without opening a write handle. */
-async function inspectSections(plan, sections, removeSectionKeys, fileSystem) {
+async function inspectSections(plan, sections, removeSectionKeys, fileSystem, validateContent = true) {
     const desired = sections.map(({ key, body }) => ({
         key,
         block: buildSection(key, body),
@@ -505,7 +506,7 @@ async function inspectSections(plan, sections, removeSectionKeys, fileSystem) {
         ? ''
         : await fileSystem.readFile(plan.targetPath, 'utf8');
     const classification = classifySections(plan, desired, content, removeSectionKeys);
-    await assertPlanUnchanged(plan, fileSystem, plan.kind === 'missing' ? undefined : content);
+    await assertPlanUnchanged(plan, fileSystem, plan.kind === 'missing' || !validateContent ? undefined : content);
     return { content, desired, classification };
 }
 async function upsertSectionsInternal(repoRoot, sections, removeSectionKeys, fileSystem, allowReplan) {
@@ -518,7 +519,7 @@ async function upsertSectionsInternal(repoRoot, sections, removeSectionKeys, fil
         return Object.fromEntries(sections.map(({ key }) => [key, blocked]));
     }
     try {
-        const { desired, content, classification } = await inspectSections(plan, sections, removeSectionKeys, fileSystem);
+        let { desired, content, classification } = await inspectSections(plan, sections, removeSectionKeys, fileSystem, false);
         if (plan.kind === 'missing') {
             const creation = await createMissingFile(plan, `${desired.map(({ block }) => block).join('\n\n')}\n`, fileSystem);
             if (creation === 'created')
@@ -528,12 +529,29 @@ async function upsertSectionsInternal(repoRoot, sections, removeSectionKeys, fil
             }
             throw new Error(IDENTITY_CHANGED);
         }
+        if (classification.absentBlocks.length === 0) {
+            // Non-appending outcomes retain their original content-stability check
+            // without creating a lock; only append candidates use the locked re-read.
+            await assertPlanUnchanged(plan, fileSystem, content);
+            return classification.results;
+        }
         if (classification.absentBlocks.length > 0) {
-            const appended = await appendAbsentSections(plan, classification.absentBlocks, fileSystem);
-            if (appended.kind === 'blocked')
-                throw new Error(appended.reason);
-            if (appended.kind === 'refused') {
-                return classifySections(plan, desired, content, removeSectionKeys, appended.cause).results;
+            const release = await acquireAgentsMdAppendLock(plan.repoRoot, plan.targetPath);
+            try {
+                // Revalidate the original identity and classify fresh bytes under the lock.
+                ({ desired, content, classification } = await inspectSections(plan, sections, removeSectionKeys, fileSystem));
+                if (classification.absentBlocks.length > 0) {
+                    const appended = await appendAbsentSections(plan, classification.absentBlocks, fileSystem);
+                    if (appended.kind === 'blocked')
+                        throw new Error(appended.reason);
+                    if (appended.kind === 'refused') {
+                        return classifySections(plan, desired, content, removeSectionKeys, appended.cause).results;
+                    }
+                }
+                return classification.results;
+            }
+            finally {
+                await release();
             }
         }
         return classification.results;

package/dist/commands/shared/frontmatter.d.ts

@@ -24,7 +24,7 @@ export declare const SKILL_GATE_OVERRIDE_SOURCE = "state.md:oat_skill_gate_overr
  * `skills.test.ts` pins this constant against the live `oat_gateable: true`
  * declarations so the two cannot drift apart.
  */
-export declare const GATE_AWARE_SKILLS: readonly ['oat-project-implement', 'oat-project-import-plan', 'oat-project-lite', 'oat-project-plan', 'oat-project-quick-start'];
+export declare const GATE_AWARE_SKILLS: readonly ['oat-project-brief', 'oat-project-implement', 'oat-project-import-plan', 'oat-project-lite', 'oat-project-plan', 'oat-project-quick-start'];
 export type SkillGateOverrideValue = typeof SKILL_GATE_OVERRIDE_DISABLED;
 export interface ProjectSkillGateOverrides {
     /** False when the key is absent entirely: absence means follow configuration. */

package/dist/commands/shared/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,mBAAmB,YAAI,gBAAgB,EAAE,cAAc,CAAU,CAAC;AAE/E,eAAO,MAAM,oBAAoB,YAC/B,WAAW,EACX,MAAM,EACN,QAAQ,EACR,MAAM,EACN,WAAW,EACX,eAAe,CACP,CAAC;AAEX,eAAO,MAAM,gCAAgC,YAC3C,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,mCAAmC,EACnC,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,2BAA2B,EAC3B,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,mBAAmB,CACX,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,4BAA4B,CAIvC;AAID,eAAO,MAAM,yBAAyB,6BAA6B,CAAC;AACpE,eAAO,MAAM,4BAA4B,aAAa,CAAC;AACvD,eAAO,MAAM,0BAA0B,sCAA0C,CAAC;AAElF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,YAC5B,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,CACjB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,OAAO,4BAA4B,CAAC;AAEzE,MAAM,WAAW,yBAAyB;IACxC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACnD;AAQD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,yBAAyB,CA0F3B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA4BpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CASjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,0BAA0B,EAAE,OAAO,CAAC;IACpC,sEAAsE;IACtE,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;IACjC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAuCD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAoD3E;AAeD;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,GACZ,CAAC,kBAAkB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,CAsB1C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,sBAAsB,GAC7B,oBAAoB,GAAG,IAAI,CAwB7B;AAgBD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/commands/shared/frontmatter.js

@@ -69,6 +69,7 @@ export const SKILL_GATE_OVERRIDE_SOURCE = `state.md:${SKILL_GATE_OVERRIDE_FIELD}
  * declarations so the two cannot drift apart.
  */
 export const GATE_AWARE_SKILLS = [
+    'oat-project-brief',
     'oat-project-implement',
     'oat-project-import-plan',
     'oat-project-lite',

package/dist/commands/state/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAmB9E,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA0ID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAC/B,OAAO,CAET;AAomBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAkF9B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAoB9E,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA0ID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAC/B,OAAO,CAET;AA0pBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAkF9B"}

package/dist/commands/state/generate.js

@@ -11,7 +11,7 @@ import { resolveProjectsRoot } from '../shared/oat-paths.js';
 import { resolveScopeRoot } from '../shared/project-scope.js';
 import { readOatLocalConfig } from '../../config/oat-config.js';
 import { ensureDir, fileExists } from '../../fs/io.js';
-import { evaluateQuickPlanReadiness, quickPlanNotReadyReason, } from '@open-agent-toolkit/control-plane';
+import { BRIEF_MODES, evaluateQuickPlanReadiness, quickPlanNotReadyReason, } from '@open-agent-toolkit/control-plane';
 import YAML from 'yaml';
 const defaultGit = {
     isGitRepo(root) {
@@ -238,6 +238,24 @@ function calculateStaleness(knowledge, git, repoRoot, today) {
     }
     return result;
 }
+/**
+ * True when the frontmatter workflow mode belongs to the brief mode family.
+ * The dashboard keeps the raw frontmatter string, so it checks membership
+ * against the control plane's registry rather than a local list.
+ */
+function isBriefWorkflow(workflowMode) {
+    return BRIEF_MODES.includes(workflowMode);
+}
+/**
+ * Printed for brief projects in the implement phase, where the router's
+ * brief-unit guard applies. The dashboard reads `state.md` frontmatter only
+ * and never phase-unit progress, so it cannot apply that guard at
+ * `implement:complete`/`pr_open`.
+ */
+const BRIEF_ROUTER_AUTHORITY_NOTE = '> Brief projects count progress in phase-units, which this dashboard does not read. ' +
+    '`oat project status` and `oat-project-next` use the control-plane router, which is the ' +
+    'authority for the brief-unit guard: an unaccepted phase-unit sends the project back to ' +
+    '`oat-project-implement` before any finalization step.';
 function computeNextStep(project, hasProjects, state) {
     if (project.status === 'not set') {
         if (project.lastPausedProject) {
@@ -283,11 +301,15 @@ function computeNextStep(project, hasProjects, state) {
         // projects whose state.md still lists `spec` in oat_hill_checkpoints route
         // to oat-project-design here so they finish through the consolidated flow
         // rather than being pushed back at the deprecated standalone skill.
+        // Brief modes own their plan phase through the brief entry skill, as the
+        // router's mode-aware current-phase lookup does.
         const phaseSkillMap = {
             discovery: 'oat-project-discover',
             spec: 'oat-project-design',
             design: 'oat-project-design',
-            plan: 'oat-project-plan',
+            plan: isBriefWorkflow(state.workflowMode)
+                ? 'oat-project-brief'
+                : 'oat-project-plan',
             implement: 'oat-project-implement',
         };
         return {
@@ -366,6 +388,25 @@ function computeNextStep(project, hasProjects, state) {
             step: 'oat-project-lite',
             reason: 'Continue lite planning',
         },
+        // Brief routes mirror the router's BRIEF_ROUTES. Parity with
+        // `recommendSkill` is bounded to these plan-phase states and
+        // `implement:in_progress` (generate.test.ts pins it): this dashboard has no
+        // phase-unit progress, so at `implement:complete`/`pr_open` a brief follows
+        // the shared post-implementation map below and the router, reached through
+        // `oat project status` and `oat-project-next`, is the authority for the
+        // brief-unit guard. The dashboard prints a note saying so.
+        'brief:plan:in_progress': {
+            step: 'oat-project-brief',
+            reason: 'Continue the project brief',
+        },
+        'brief:plan:complete': {
+            step: 'oat-project-implement',
+            reason: 'Start implementation from the approved brief',
+        },
+        'brief:implement:in_progress': {
+            step: 'oat-project-implement',
+            reason: 'Continue implementation',
+        },
     };
     if (routeMap[key])
         return routeMap[key];
@@ -563,6 +604,13 @@ function buildDashboardMarkdown(project, state, knowledge, staleness, nextStep,
     lines.push('');
     lines.push(`**${nextStep.step}** - ${nextStep.reason}`);
     lines.push('');
+    if (project.status === 'active' &&
+        state &&
+        state.phase === 'implement' &&
+        isBriefWorkflow(state.workflowMode)) {
+        lines.push(BRIEF_ROUTER_AUTHORITY_NOTE);
+        lines.push('');
+    }
     lines.push('## Quick Commands');
     lines.push('');
     lines.push('- `oat-project-progress` - Check current status');
@@ -571,6 +619,7 @@ function buildDashboardMarkdown(project, state, knowledge, staleness, nextStep,
     lines.push('- `oat-project-quick-start` - Create a quick workflow project');
     lines.push('- `oat-project-import-plan` - Import an external provider plan');
     lines.push('- `oat-project-lite` - Create a lite workflow project');
+    lines.push('- `oat-project-brief` - Create a brief workflow project');
     lines.push('- `oat project open <name>` - Open or resume a project');
     lines.push('- `oat project pause [name]` - Pause active or named project');
     lines.push('- `oat-project-complete` - Mark project complete');

package/dist/commands/tools/shared/pack-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack-manifest.d.ts","sourceRoot":"","sources":["../../../../src/commands/tools/shared/pack-manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,QAAQ,EACT,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACf,CAAC;AAEF,eAAO,MAAM,UAAU,4GASiB,CAAC;AAEzC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAoID,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EA2LlD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAMhE;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE,aAAa,GACnB,SAAS,mBAAmB,EAAE,CAGhC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAC9C,MAAM,EAAE,CAQV;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAIlE;AAoJD,wBAAgB,oBAAoB,CAClC,QAAQ,GAAE,SAAS,cAAc,EAAkB,GAClD,IAAI,CAiEN"}
+{"version":3,"file":"pack-manifest.d.ts","sourceRoot":"","sources":["../../../../src/commands/tools/shared/pack-manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,QAAQ,EACT,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACf,CAAC;AAEF,eAAO,MAAM,UAAU,4GASiB,CAAC;AAEzC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAqID,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EA6LlD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAMhE;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE,aAAa,GACnB,SAAS,mBAAmB,EAAE,CAGhC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAC9C,MAAM,EAAE,CAQV;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAIlE;AAoJD,wBAAgB,oBAAoB,CAClC,QAAQ,GAAE,SAAS,cAAc,EAAkB,GAClD,IAAI,CAiEN"}

package/dist/commands/tools/shared/pack-manifest.js

@@ -77,6 +77,7 @@ const WORKFLOW_SKILL_NAMES = [
     'oat-cursor-cloud-projects',
     'oat-explainer-kit',
     'oat-project-autonomous',
+    'oat-project-brief',
     'oat-project-capture',
     'oat-project-clear-active',
     'oat-project-complete',
@@ -193,7 +194,9 @@ export const PACK_MANIFEST = [
                 'design.md',
                 'plan.md',
                 'plan-lite.md',
+                'plan-brief.md',
                 'implementation.md',
+                'implementation-brief.md',
                 'summary.md',
                 'project-log.md',
                 'project-retro.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -35,7 +35,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.17"
+    "@open-agent-toolkit/control-plane": "0.3.19"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",