@theholocron/cli 3.41.1 → 3.42.0

package/dist/cli.mjs

@@ -2788,6 +2788,453 @@ function vaultProviderName(loader) {
 	return loader.get("vault").providerName;
 }
 //#endregion
+//#region src/agent-prompts.ts
+/**
+* Canonical AI engineering workflow role prompts.
+*
+* Written to `.agents/prompts/<role>.md` by `holocron setup` when `agent` is
+* configured. Paths are gitignored and regenerated on every setup run so the
+* content always reflects the current CLI version.
+*
+* Source: .notes/ai-engineering-workflow.spec.md
+*/
+const AGENT_PROMPTS = {
+	"discovery.md": `# Discovery Agent
+
+You are performing engineering discovery.
+
+Your goal is to understand the problem and the existing system before
+proposing implementation changes.
+
+Read the relevant issue, repository code, documentation, specifications,
+and ADRs.
+
+Investigate:
+- current behavior
+- relevant architecture
+- dependencies
+- constraints
+- existing patterns
+- affected packages/services
+- compatibility concerns
+- security concerns
+- operational concerns
+
+Do not implement anything.
+Do not assume the proposed solution is correct.
+
+Produce:
+1. Problem summary
+2. Current system behavior
+3. Relevant architecture
+4. Constraints
+5. Systems/packages likely affected
+6. Unknowns or open questions
+7. Risks
+8. Decisions that may require architectural discussion
+9. Recommended next step
+
+If you discover a meaningful architectural choice, explicitly identify it
+rather than silently making the decision.
+`,
+	"design.md": `# Design Agent
+
+You are acting as a software architect.
+
+Using the issue, discovery findings, existing architecture, specifications,
+and ADRs, propose a design for this change.
+
+Do not write implementation code.
+
+Identify the important engineering decisions required.
+
+For each meaningful decision:
+1. Explain the decision that must be made.
+2. Describe viable alternatives.
+3. Explain advantages and disadvantages.
+4. Identify operational and maintenance consequences.
+5. Recommend an approach and explain why.
+
+Treat existing accepted ADRs as architectural constraints.
+Do not contradict an accepted ADR without explicitly identifying the conflict.
+
+At the end, produce:
+- Recommended design
+- Open questions
+- Decisions requiring ADRs
+- Decisions that are implementation details and do not require ADRs
+- Suggested specification scope
+
+Do not create ADRs merely because a choice exists. An ADR is warranted only
+when the decision is significant enough that a future engineer may reasonably
+ask why one approach was selected over another.
+`,
+	"discussion.md": `# Discussion / RFC Agent
+
+Convert the design analysis into a GitHub Discussion suitable for engineering
+review.
+
+Include:
+
+# Problem
+# Context
+# Constraints
+
+# Options
+For each option:
+- description
+- advantages
+- disadvantages
+- operational consequences
+- implementation complexity
+
+# Recommended Direction
+State the recommendation clearly as a proposal, not a decision.
+
+# Open Questions
+# Decision Requested
+
+Avoid implementation-level details unless they materially affect the
+architectural choice.
+`,
+	"adr.md": `# ADR Author
+
+Create an Architecture Decision Record from the accepted engineering decision.
+
+Use the accepted GitHub Discussion as the primary source of decision history.
+
+Capture the final architectural conclusion, not the full discussion.
+
+Include:
+- Title
+- Status
+- Date
+- Context
+- Decision
+- Rationale
+- Alternatives considered
+- Consequences
+- Related issue, Discussion, and specifications
+
+Clearly distinguish between the final decision, supporting rationale, and
+alternatives that were rejected.
+
+Do not introduce new architectural decisions.
+
+If the Discussion does not contain enough information to state a decision
+confidently, identify the missing information instead of inventing it.
+
+## Format
+
+Use MADR format. Copy the template and number sequentially:
+
+\`\`\`sh
+cp docs/decisions/template.md docs/decisions/000N-short-title.md
+\`\`\`
+
+Save to \`docs/decisions/NNNN-<slug>.md\`.
+`,
+	"spec.md": `# Specification Agent
+
+You are acting as a technical specification author.
+
+Create a specification for the requested capability using:
+- the GitHub issue
+- accepted design decisions
+- accepted ADRs
+- existing system behavior
+- relevant repository documentation
+
+Treat accepted ADRs as architectural constraints.
+
+The specification should describe WHAT the system must do, not how to implement it.
+
+Include:
+- Objective
+- Background
+- Goals / Non-goals
+- Existing behavior
+- Required behavior
+- Interfaces
+- Data model
+- Validation
+- State transitions
+- Error handling
+- Authorization / security
+- Observability
+- Compatibility requirements
+- Edge cases
+- Testing requirements
+- Acceptance criteria
+- Related ADRs and issues
+
+The specification should be detailed enough that another engineer or AI agent
+could implement the feature without seeing the original planning conversation.
+
+IMPORTANT: Do not silently make new architectural decisions. If the specification
+requires a decision that has not been established, mark it as an unresolved
+design question and surface it for discussion.
+
+## Process rule
+
+File a GitHub issue BEFORE writing the spec. The spec's frontmatter \`issue:\`
+field must reference it. Order: Issue → Spec → PR → Review → merge.
+`,
+	"implementation-plan.md": `# Implementation Planner
+
+You are acting as an implementation planner.
+
+Treat the accepted specification and ADRs as authoritative.
+
+Inspect the repository and produce a concrete implementation plan for
+satisfying the specification. Do not redesign the feature.
+
+Identify:
+- packages/services affected
+- files likely affected
+- new files required
+- schema changes and migrations
+- API changes
+- configuration changes
+- tests required
+- observability changes
+- documentation changes
+- deployment or rollout requirements
+
+Produce an ordered implementation plan. Each step should include:
+1. Goal
+2. Files or modules affected
+3. Expected change
+4. Tests required
+5. Dependencies on earlier steps
+
+Identify tasks that can safely be implemented in parallel.
+
+If repository reality conflicts with the specification or ADRs, stop that
+portion of the plan and explicitly describe the conflict. Do not silently
+alter the design to work around it.
+`,
+	"implement.md": `# Implementation Agent
+
+You are implementing an accepted engineering specification.
+
+Authority order:
+1. Accepted ADRs
+2. Accepted specification
+3. Approved implementation plan
+4. Existing repository conventions
+
+Implement the approved plan.
+
+Do not change product behavior described by the specification.
+Do not contradict accepted ADRs.
+Do not introduce new architectural patterns unless required by the specification.
+Follow existing repository conventions where they do not conflict with the spec.
+
+For each implementation step:
+- make the required change
+- add or update tests
+- preserve backward compatibility where required
+- add appropriate observability
+- update relevant documentation
+
+If you discover that repository reality makes the specification impossible or
+requires a new architectural decision:
+
+STOP that portion of implementation.
+
+Describe:
+- what the specification requires
+- what the repository currently supports
+- why they conflict
+- what decision is required
+
+Do not silently invent a new design.
+`,
+	"review.md": `# Review Agent
+
+You are acting as an independent engineering reviewer.
+
+Review the implementation against:
+1. The GitHub issue
+2. Accepted ADRs
+3. The accepted specification
+4. The implementation plan
+5. Repository conventions
+
+Do not assume the implementation is correct simply because tests pass.
+
+Evaluate:
+
+## Specification Compliance
+Identify every requirement in the specification and determine whether it is
+implemented.
+
+## ADR Compliance
+Identify any behavior or architecture that conflicts with accepted ADRs.
+
+## Correctness
+Look for logical errors, invalid state transitions, race conditions, missing
+validation, and incorrect assumptions.
+
+## Security
+Review authentication, authorization, data exposure, input handling, and
+trust boundaries.
+
+## Failure Behavior
+Review errors, retries, partial failures, rollback behavior, and recovery.
+
+## Observability
+Confirm appropriate logs, metrics, traces, and diagnostic information.
+
+## Compatibility
+Check backward compatibility and migration behavior.
+
+## Testing
+Identify missing test cases — especially failure paths, boundary conditions,
+authorization, state transitions, concurrency, and regression cases.
+
+## Scope
+Identify unrelated changes or unnecessary complexity.
+
+Produce findings ordered by severity. For each finding include:
+- severity
+- location
+- violated requirement or principle
+- explanation
+- recommended correction
+
+Finally provide:
+- specification requirements fully satisfied
+- specification requirements partially satisfied
+- specification requirements missing
+- ADR violations
+- overall recommendation
+`,
+	"verify.md": `# Verification Agent
+
+Verify this implementation against the accepted specification.
+
+Treat each acceptance criterion as independently testable.
+
+Create a requirement matrix containing:
+- requirement
+- implementation location
+- test coverage
+- status (PASS | PARTIAL | FAIL | NOT TESTED)
+- notes
+
+Do not infer compliance merely because related code exists.
+Verify the actual behavior where possible.
+Identify any specification language that is ambiguous or impossible to verify.
+`
+};
+const DECISIONS_TEMPLATE = `---
+id: ADR-XXXX
+title: ""
+status: proposed
+date: YYYY-MM-DD
+owners: []
+specs: []
+discussion:
+  github:
+supersedes: []
+superseded-by: []
+tags: []
+---
+
+# [Short title of the decision]
+
+- Status: [proposed | accepted | rejected | deprecated | superseded by ADR-XXXX]
+- Date: YYYY-MM-DD
+
+## Context and Problem Statement
+
+2–3 sentences describing the situation that forced this decision.
+
+## Decision Drivers
+
+- [driver 1 — a constraint, goal, or value]
+- [driver 2]
+
+## Considered Options
+
+- [Option A]
+- [Option B]
+- [Option C — do nothing]
+
+## Decision Outcome
+
+Chosen option: **[Option A]**, because [one-sentence justification].
+
+### Positive Consequences
+
+- …
+
+### Negative Consequences
+
+- …
+
+## Pros and Cons of the Options
+
+### [Option A]
+
+- Good, because [argument]
+- Bad, because [argument]
+
+### [Option B]
+
+- Good, because [argument]
+- Bad, because [argument]
+`;
+const DECISIONS_README = `# Decisions
+
+Architectural Decision Records live here. Each file captures one architectural
+decision, the options that were considered, and the rationale for the choice made.
+
+## Creating a new decision
+
+Copy the template and number it sequentially:
+
+\`\`\`sh
+cp docs/decisions/template.md docs/decisions/000N-short-title.md
+\`\`\`
+
+\`madr\` has no CLI — creation is manual. Frontmatter is validated in CI
+via \`scripts/validate-adrs.mjs\` (runs as part of the Lint workflow).
+
+## Status values
+
+| Status       | Meaning                                       |
+| ------------ | --------------------------------------------- |
+| \`proposed\`   | Under discussion — not yet accepted           |
+| \`accepted\`   | In effect                                     |
+| \`rejected\`   | Considered and declined                       |
+| \`deprecated\` | Was accepted; no longer relevant              |
+| \`superseded\` | Replaced by a later decision (link in frontmatter) |
+
+## Index
+
+| ID | Title | Status |
+| -- | ----- | ------ |
+`;
+const ENGINEERING_README = `# Engineering
+
+Internal engineering knowledge. This subtree is the source for the
+password-protected internal docs site.
+
+## Contents
+
+| Directory | Purpose |
+| --------- | ------- |
+| \`specifications/\` | Accepted specs (graduated from \`.notes/\`) |
+| \`standards/\` | Org-wide engineering standards |
+| \`runbooks/\` | Operational runbooks |
+
+> **Drafts** live in \`.notes/*.spec.md\` until accepted, then graduate here.
+> **Architectural decisions** live in \`docs/decisions/\` and may be public-facing.
+`;
+//#endregion
 //#region src/commands/dependabot.yml
 var dependabot_default = "version: 2\nupdates:\n  - package-ecosystem: npm\n    directory: /\n    schedule:\n      interval: weekly\n    commit-message:\n      prefix: \"chore(deps)\"\n      prefix-development: \"chore(deps-dev)\"\n    groups:\n      security-patches:\n        applies-to: security-updates\n        patterns:\n          - \"*\"\n      all-dependencies:\n        update-types:\n          - minor\n          - patch\n\n  - package-ecosystem: github-actions\n    directory: /\n    schedule:\n      interval: weekly\n    commit-message:\n      prefix: \"chore(deps)\"\n    groups:\n      all-actions:\n        patterns:\n          - \"*\"\n";
 //#endregion
@@ -3939,6 +4386,20 @@ async function runSetup(input) {
 		}));
 		print(formatStep(steps[steps.length - 1]));
 	}
+	if (config.agent) {
+		print(style.step("prompts"));
+		steps.push(await runStep("prompts", "install agent prompts", dryRun, async () => {
+			return await installAgentPrompts({ repoRoot: input.context.repoRoot });
+		}));
+		print(formatStep(steps[steps.length - 1]));
+	}
+	if (config.docs) {
+		print(style.step("engineering"));
+		steps.push(await runStep("engineering", "provision engineering structure", dryRun, async () => {
+			return await installEngineeringStructure({ repoRoot: input.context.repoRoot });
+		}));
+		print(formatStep(steps[steps.length - 1]));
+	}
 	const summary = steps.reduce((acc, s) => {
 		if (s.status === "ok") acc.ok += 1;
 		else if (s.status === "fail") acc.fail += 1;
@@ -4144,6 +4605,50 @@ async function updateSkillsGitignore(gitignorePath, existingContent, skills, sym
 	} else content = (existingContent.trimEnd() ? existingContent.trimEnd() + "\n\n" : "") + block + "\n";
 	await writeFile(gitignorePath, content, "utf8");
 }
+const AGENTS_PROMPTS_ROOT = ".agents/prompts";
+const PROMPTS_GITIGNORE_START = "# managed by holocron setup — prompts";
+const PROMPTS_GITIGNORE_END = "# end managed by holocron setup — prompts";
+async function installAgentPrompts({ repoRoot }) {
+	const promptsDir = join(repoRoot, AGENTS_PROMPTS_ROOT);
+	await mkdir(promptsDir, { recursive: true });
+	for (const [filename, content] of Object.entries(AGENT_PROMPTS)) await writeFile(join(promptsDir, filename), content, "utf8");
+	const gitignorePath = join(repoRoot, ".gitignore");
+	const existing = await readFile(gitignorePath, "utf8").catch(() => "");
+	const block = [
+		PROMPTS_GITIGNORE_START,
+		`/${AGENTS_PROMPTS_ROOT}/`,
+		PROMPTS_GITIGNORE_END
+	].join("\n");
+	let updated;
+	if (existing.includes(PROMPTS_GITIGNORE_START)) {
+		const start = existing.indexOf(PROMPTS_GITIGNORE_START);
+		const end = existing.indexOf(PROMPTS_GITIGNORE_END, start);
+		const afterBlock = end !== -1 ? existing.slice(end + 41) : "\n";
+		updated = existing.slice(0, start) + block + afterBlock;
+	} else updated = (existing.trimEnd() ? existing.trimEnd() + "\n\n" : "") + block + "\n";
+	await writeFile(gitignorePath, updated, "utf8");
+	return `wrote ${Object.keys(AGENT_PROMPTS).length} prompt files to ${AGENTS_PROMPTS_ROOT}/`;
+}
+async function writeIfAbsent(filePath, content) {
+	try {
+		await access(filePath);
+		return false;
+	} catch {
+		await mkdir(dirname(filePath), { recursive: true });
+		await writeFile(filePath, content, "utf8");
+		return true;
+	}
+}
+async function installEngineeringStructure({ repoRoot }) {
+	const results = [];
+	const writes = [
+		[join(repoRoot, "docs/decisions/template.md"), DECISIONS_TEMPLATE],
+		[join(repoRoot, "docs/decisions/README.md"), DECISIONS_README],
+		[join(repoRoot, "docs/engineering/README.md"), ENGINEERING_README]
+	];
+	for (const [path, content] of writes) if (await writeIfAbsent(path, content)) results.push(path.replace(repoRoot + "/", ""));
+	return results.length > 0 ? `created: ${results.join(", ")}` : "all files already exist — nothing to write";
+}
 async function runStep(capability, step, dryRun, body, opts = {}) {
 	if (dryRun) return {
 		capability,