@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/dist/core/src/onboarding/agentsGuide.js

@@ -0,0 +1,164 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isNotFound, readTextFile } from "../fs/index.js";
+export const AGENTS_GUIDE_PATH = "AGENTS.md";
+export const AGENTS_GUIDE_TEMPLATE_ID = "openworkflow.agents-guide.v1";
+export const AGENTS_GUIDE_BEGIN = `<!-- BEGIN OPENWORKFLOW AGENT GUIDE generated-by: openworkflow; template-id: ${AGENTS_GUIDE_TEMPLATE_ID} -->`;
+export const AGENTS_GUIDE_END = "<!-- END OPENWORKFLOW AGENT GUIDE -->";
+export function renderAgentsGuide() {
+    return `${AGENTS_GUIDE_BEGIN}
+## OpenWorkflow
+
+- Run \`openworkflow --help\` first when you need current CLI capabilities, workflow command boundaries, or maintenance commands.
+- Prefer \`--json\` for structured command output; every OpenWorkflow CLI command supports a JSON report envelope for Agent consumption.
+- Treat JSON \`ok:false\` as a failed command: OpenWorkflow exits nonzero but still writes the parseable JSON report to stdout. Read \`health_errors\` for blocking health/readiness failures, \`errors\` for command/runtime failures, and \`warnings\` for non-blocking guidance.
+- Use \`openworkflow resume --root . --json\` as the first recovery command when a fresh Agent is asked to continue after network loss, context overflow, compaction failure, or unexpected termination. Resume is the minimal-context precision entrypoint for project overview, current queue/work item, breakpoint, behavior boundaries, allowed work, validation expectations, git state, and the smallest correct OW-maintained next action.
+- Run \`openworkflow handoff --root . --json\` as the strict Agent trust gate before loading context; it aggregates managed surface health, strict summary quality, current pointers, next-command readiness, read order, blockers, and next actions.
+- Use \`openworkflow context --root . --handoff --json\` when you need both a bounded startup packet and strict handoff-quality blocking in one command; default \`context --json\` remains packet-only and may return \`ok:true\` with handoff warnings.
+- Start with \`openworkflow inspect --root . --json\` for the aggregated Agent entry read model, health, next-command readiness, and read order; add \`--strict\` when current-but-thin summary quality should block handoff trust.
+- Treat \`openworkflow doctor --root . --json\` as a managed-surface maintenance check; its top-level \`ok\` does not prove artifact handoff quality. Read \`handoff_quality_ok\` or use \`inspect --strict\` / \`summaries --strict\` for handoff gates.
+- Start every workflow turn by reading \`.openworkflow/CURRENT_STATE.yaml\`, then follow its \`read_this_first\` pointers before loading full evidence.
+- When dogfooding OpenWorkflow inside its own repository, use OpenWorkflow commands as the read model and trust gate before implementation, but make durable product changes in the source files that generate the managed surfaces.
+- Treat each \`decompose-to-changes\` \`CANDIDATE_CHANGES.yaml\` queue as the feat boundary. Create one top-level \`changes/<feat-id>/\` folder for that queue, then treat each selected candidate inside it as a commit-sized change with selection, atom-task, and brief artifacts kept under the feat folder.
+- Do not create a new top-level feat folder for every small candidate. Open a new top-level \`changes/<feat-id>/\` only when a new decomposition queue or product theme is needed; otherwise advance the current feat through focused commits.
+- Do not manually patch generated or managed surfaces such as \`.openworkflow/**\`, \`.agents/skills/ow-*/SKILL.md\`, or \`AGENTS.md\` to fix product behavior; update the registry, artifact contracts, templates, schemas, or tests that produce them, then run \`openworkflow sync\` or \`init\` to regenerate.
+- CLI commands maintain and summarize the repo-local workflow surface: \`init\`, \`sync\`, \`validate\`, \`doctor\`, \`handoff\`, \`resume\`, \`inspect\`, \`context\`, \`draft\`, \`register\`, \`status\`, \`brief\`, \`check\`, \`summaries\`, and \`clean\`.
+- Use \`resume --json\` for interrupted-session recovery. Use \`handoff --json\` when you only need the strict trust gate, \`context --json\` when you need a bounded packet for a known \`/ow:*\` command, \`inspect --json\` when you need the aggregated read model and read order, and \`status\` or \`brief\` when you need a lightweight state summary. Do not treat resume as a generic autonomous retry loop; it should route the Agent into corrected, ranked atom-task continuation with explicit product-alignment and stop boundaries.
+- Use \`openworkflow context --root . --json\` to materialize a compact startup packet for \`CURRENT_STATE.next_command\`; compact mode returns a structured \`command_audit\` slice instead of full audit source. Add \`--handoff\` when thin or stale summaries should make the packet fail, and add \`--for /ow:<command>\`, \`--max-bytes <n>\`, or \`--mode full\` when you need a specific workflow command, tighter budget, or full managed audit source.
+- In \`context --json\` and \`doctor --json\`, read \`data.handoff_quality_ok\` and \`data.quality_summary\` before trusting low-context handoff artifacts; \`quality_summary.status\` tells you whether summaries are trusted, need refresh, or are current-but-thin.
+- Use \`openworkflow draft --root . --artifact <type> --id <id> --json\` to preview a contract-shaped source artifact; add \`--write\` only when the active \`/ow:*\` workflow step should create that artifact.
+- Use \`openworkflow register --root . --artifact <path> --json\` after a source artifact exists to preview index registration; add \`--write\` to make it visible to read models, and \`--current\` only when it should become the active pointer.
+- Use \`openworkflow brief --root .\` or \`openworkflow status --root .\` for a low-context Agent read model before deciding what to inspect next; use \`--json\` when another tool needs structured data.
+- Use \`openworkflow check /ow:<command> --root . --json\` before uncertain workflow work to verify required context, forbidden context, output boundaries, current artifact usability, and next actions.
+- Use \`openworkflow summaries --root . --json\` before loading raw evidence when artifact summaries or current slices may be missing, stale, or current-but-thin; add \`--strict\` to make draft/thin source quality return \`ok:false\`. Freshness and source artifact quality are separate signals.
+- Use \`openworkflow summarize --root . --artifact <path> --json\` to preview SUMMARY.yaml refreshes; add \`--write\` only when you intend to update summary files without changing source artifacts.
+- Use \`openworkflow validate --root . --json\` for contract shape; SUMMARY.yaml trust is checked by \`summaries\`, not by \`validate\`.
+- Use \`openworkflow clean --root . --tools codex --json\` to preview managed/generated cleanup; \`--yes\` removes OpenWorkflow managed metadata and generated adapter files while preserving source artifacts, SUMMARY.yaml, evidence, notes, and user AGENTS.md content.
+- Repo-local workflow commands are delivered as Agent skills under \`.agents/skills/ow-*/SKILL.md\` and map to semantic commands: \`/ow:vision\`, \`/ow:validation\`, \`/ow:proto\`, \`/ow:tune\`, \`/ow:design\`, \`/ow:spec\`, \`/ow:change\`, \`/ow:team\`, \`/ow:decompose-to-changes\`, \`/ow:analyze-changes\`, \`/ow:select-change\`, and \`/ow:git-automation\`.
+- Respect lazy creation: \`openworkflow init\` only creates the minimal workflow root; stage artifacts must be created only by the first matching \`/ow:*\` command.
+- Project-local \`SOUL.md\` and \`MEMORY.md\` are future governed learning artifacts. Do not conflate them with the resume packet; resume may surface trusted signals later, but it does not create or evolve persistent project personality or memory.
+- Prefer summary/current-state files for orientation, and load raw evidence only when the current task requires it.
+${AGENTS_GUIDE_END}
+`;
+}
+export async function syncAgentsGuide(root) {
+    const path = join(root, AGENTS_GUIDE_PATH);
+    const existing = await readOptional(path);
+    const next = upsertAgentsGuide(existing);
+    if (!next.changed) {
+        return { path, action: "unchanged" };
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, next.content, "utf8");
+    return { path, action: next.action };
+}
+export async function doctorAgentsGuide(root) {
+    const path = join(root, AGENTS_GUIDE_PATH);
+    const content = await readOptional(path);
+    if (content === null) {
+        return {
+            ok: true,
+            warnings: [`${AGENTS_GUIDE_PATH} is missing; run openworkflow sync to create the Agent onboarding guide.`],
+            errors: [],
+        };
+    }
+    if (!hasAgentsGuide(content)) {
+        return {
+            ok: true,
+            warnings: [`${AGENTS_GUIDE_PATH} has no OpenWorkflow managed block; run openworkflow sync to append it without changing existing content.`],
+            errors: [],
+        };
+    }
+    if (!isAgentsGuideCurrent(content)) {
+        return {
+            ok: true,
+            warnings: [`${AGENTS_GUIDE_PATH} OpenWorkflow managed block is stale; run openworkflow sync to refresh it.`],
+            errors: [],
+        };
+    }
+    return { ok: true, warnings: [], errors: [] };
+}
+export async function cleanAgentsGuide(options) {
+    const dryRun = !options.yes;
+    const path = join(options.root, AGENTS_GUIDE_PATH);
+    const planned = [];
+    const removed = [];
+    const updated = [];
+    const skipped = [];
+    const preserved = [];
+    const warnings = [];
+    const content = await readOptional(path);
+    if (content === null || !hasAgentsGuide(content)) {
+        return { planned, removed, updated, skipped, preserved, warnings, dryRun };
+    }
+    planned.push({ path, reason: "OpenWorkflow AGENTS.md managed block" });
+    if (dryRun) {
+        return { planned, removed, updated, skipped, preserved, warnings, dryRun };
+    }
+    const next = removeAgentsGuide(content);
+    if (!next.changed) {
+        return { planned, removed, updated, skipped, preserved, warnings, dryRun };
+    }
+    await writeFile(path, next.content, "utf8");
+    updated.push(path);
+    preserved.push(path);
+    return { planned, removed, updated, skipped, preserved, warnings, dryRun };
+}
+export function hasAgentsGuide(content) {
+    return content.includes(AGENTS_GUIDE_BEGIN) && content.includes(AGENTS_GUIDE_END);
+}
+export function isAgentsGuideCurrent(content) {
+    return hasAgentsGuide(content) && replaceAgentsGuideBlock(content, renderAgentsGuide()) === normalizeFinalNewline(content);
+}
+export function upsertAgentsGuide(existing) {
+    const guide = renderAgentsGuide();
+    if (existing === null || existing.trim() === "") {
+        return { content: guide, changed: true, action: "created" };
+    }
+    if (hasAgentsGuide(existing)) {
+        const content = replaceAgentsGuideBlock(existing, guide);
+        if (content === normalizeFinalNewline(existing)) {
+            return { content, changed: false, action: "unchanged" };
+        }
+        return { content, changed: true, action: "updated" };
+    }
+    return {
+        content: `${existing.replace(/\s+$/u, "")}\n\n${guide}`,
+        changed: true,
+        action: "appended",
+    };
+}
+export function removeAgentsGuide(existing) {
+    if (!hasAgentsGuide(existing)) {
+        return { content: existing, changed: false };
+    }
+    const content = existing.replace(blockPattern(), "").replace(/\n{3,}/gu, "\n\n").trim();
+    return {
+        content: content.length > 0 ? `${content}\n` : "",
+        changed: true,
+    };
+}
+async function readOptional(path) {
+    try {
+        return await readTextFile(path);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function replaceAgentsGuideBlock(content, replacement) {
+    return normalizeFinalNewline(content.replace(blockPattern(), replacement.trimEnd()));
+}
+function blockPattern() {
+    return new RegExp(`${escapeRegExp(AGENTS_GUIDE_BEGIN)}[\\s\\S]*?${escapeRegExp(AGENTS_GUIDE_END)}\\n?`, "u");
+}
+function normalizeFinalNewline(content) {
+    return content.endsWith("\n") ? content : `${content}\n`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+//# sourceMappingURL=agentsGuide.js.map

package/dist/core/src/onboarding/agentsGuide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentsGuide.js","sourceRoot":"","sources":["../../../../packages/core/src/onboarding/agentsGuide.ts"],"names":[],"mappings":"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"}