@spotsccc/agents-framework 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @spotsccc/agents-framework
+
+`@spotsccc/agents-framework` is an npm package that installs the `agents-framework` CLI for bootstrapping backlog-driven working agreements for coding agents inside a repository.
+
+## What It Sets Up
+
+The CLI turns agent workflow conventions into repository assets:
+
+- detects existing `.agents`, `.claude`, `AGENTS.md`, and `CLAUDE.md` configuration
+- installs backlog skills for research, planning, readiness review, and execution
+- scaffolds a shared markdown backlog in `.agents/backlog`
+- creates or updates managed blocks in `AGENTS.md` and `CLAUDE.md`
+
+The result is a repository where agent work can be routed through durable backlog artifacts instead of chat-only context.
+
+## Requirements
+
+- Node.js `>=22.12.0`
+
+## Usage
+
+Run without installing globally:
+
+```bash
+npx @spotsccc/agents-framework init
+```
+
+Target a specific repository:
+
+```bash
+npx @spotsccc/agents-framework init --cwd /path/to/project
+```
+
+Install as a project dependency and use the local binary through `npm exec`:
+
+```bash
+npm install -D @spotsccc/agents-framework
+npm exec agents-framework -- init
+```
+
+Overwrite managed files when you intentionally want to refresh generated content:
+
+```bash
+npx @spotsccc/agents-framework init --force
+```
+
+## Current Scope
+
+The current release focuses on the backlog bootstrap flow:
+
+- `agents-framework init`
+- backlog-only starter skills
+- backlog templates and directory structure
+- safe managed-block upserts for `AGENTS.md` and `CLAUDE.md`
+
+## Local Development
+
+Run commands from `apps/agents-framework`:
+
+```bash
+vp check
+vp test
+vp pack
+```
+
+Build and execute the local CLI directly:
+
+```bash
+vp pack
+node dist/cli.mjs init --cwd /path/to/project
+```

package/dist/backlog-execution.md

@@ -0,0 +1,51 @@
+# Backlog Execution
+
+Use this skill when the agent is implementing a single backlog item that has already passed readiness review and is ready for execution.
+
+## Do Not Use When
+
+- Do not use this skill when the request is still a loose idea or the work has not been turned into backlog task drafts yet. Use `backlog-research` or `backlog-planning` first.
+- Do not use this skill when the task still needs readiness review or is blocked by missing context. Use `backlog-readiness` or keep the item in `blocked/`.
+
+## Goal
+
+- Execute one ready backlog item with clear status tracking and repository-visible notes.
+- Keep code changes, task updates, and validation aligned with the same task file from start to finish.
+
+## Inputs
+
+- One ready backlog item, usually under `.agents/backlog/ready/`.
+- Linked research, dependency notes, parent context, and nearby code or tests.
+- `.agents/backlog/task-template.md` as the expected task shape when the repository uses the managed scaffold.
+
+## Workflow
+
+1. Read the backlog item, linked research, parent context, dependencies, and acceptance criteria.
+2. Move the task into `.agents/backlog/in-progress/` before making substantive code changes.
+3. Reconfirm the scoped deliverable and stop if new ambiguity makes the task no longer execution-ready.
+4. Implement only the work needed for the current item.
+5. Update `Implementation Notes`, `Verification`, and `Decision Log` in the same task file as decisions, blockers, and evidence appear.
+6. If new work is discovered outside scope, create or request a follow-up backlog item instead of widening the current one.
+7. Run the smallest useful validation that proves the change and record the exact outcome in the task file.
+8. Move the task into `.agents/backlog/done/` only when acceptance criteria, code, docs, and validation notes agree.
+
+## Output
+
+Update the same backlog task markdown that is being executed; do not split execution state across extra side files.
+
+- The task moves from `ready/` to `in-progress/`, and to `done/` only after execution is actually complete.
+- `Implementation Notes` reflects meaningful implementation details, constraints, and touched systems.
+- `Verification` records what was run, what passed or failed, and any manual checks or blockers.
+- `Decision Log` captures scope decisions, tradeoffs, and follow-up items created during execution.
+
+## Verification
+
+- Confirm the task file remains the single source of truth for execution notes and validation evidence.
+- Confirm any newly discovered out-of-scope work is represented as a follow-up backlog item instead of being silently absorbed.
+- Confirm the task directory matches reality: `in-progress/` while work is active, `done/` only after code, docs, and validation are aligned.
+
+## Constraints
+
+- If the item turns out to be under-specified, stop and route it through `backlog-readiness` or `backlog-planning`.
+- If validation cannot run, document the blocker and residual risk in the task file and keep the item out of `done`.
+- Do not quietly expand scope inside the current task.

package/dist/backlog-planning.md

@@ -0,0 +1,60 @@
+# Backlog Planning
+
+Use this skill when research exists and the next step is to create backlog task drafts for implementation.
+
+## Do Not Use When
+
+- Do not use this skill when the input is still a loose request or feature idea. Use `backlog-research` first.
+- Do not use this skill when a single backlog task draft only needs readiness review before execution. Use `backlog-readiness`.
+- Do not use this skill when a ready item is already being implemented. Use `backlog-execution`.
+
+## Goal
+
+- Convert research into backlog task drafts that are ordered, linked, and executable by agents after readiness review.
+- Remove hidden context from the plan so work can be picked up asynchronously.
+
+## Inputs
+
+- A completed research artifact, usually under `.agents/backlog/research/`.
+- Optional user clarifications when scope or sequencing is still unclear.
+- `.agents/backlog/task-template.md` as the shape for each created task draft.
+
+## Workflow
+
+1. Read the research document and extract the concrete deliverables.
+2. Identify unresolved questions that block planning; ask the user only when the decision changes scope or sequencing.
+3. Split the work into one or more focused task drafts based on delivery boundaries.
+4. Create or update task drafts under `.agents/backlog/draft/` using `task-template.md`.
+5. Capture likely sequencing, dependencies, and affected systems inside each task draft.
+6. Link every task draft back to the relevant research.
+7. Keep items in draft until `backlog-readiness` confirms they are ready for execution.
+
+## Planning Rules
+
+- Prefer small tasks with clear outcomes over large mixed-scope items.
+- Split discovery work from implementation work when uncertainty is still high.
+- Use separate task drafts and explicit dependency notes instead of burying sequencing inside prose.
+- Each task should describe what changes, where it likely changes, and how success will be checked.
+- The managed scaffold currently supports task-level backlog items; do not invent a separate hierarchy unless the repository already uses one.
+
+## Output
+
+Each planning pass should produce one or more task drafts in `.agents/backlog/draft/`.
+
+Each task draft should include:
+
+- a stable human-readable file name and title;
+- scope and acceptance criteria that describe the expected result;
+- implementation notes with dependencies and likely affected files or systems;
+- links back to the relevant research;
+- a verification plan that another agent can execute.
+
+## Verification
+
+- Confirm every meaningful deliverable from the research is represented by a task draft or an explicit follow-up item.
+- Confirm each task draft is narrow enough that `backlog-readiness` could realistically mark it ready after review.
+- Confirm sequencing, dependencies, and research links are visible in the repository rather than implied in chat.
+
+## Next Step
+
+- Hand each task draft to `backlog-readiness` before moving it into `ready/`.

package/dist/backlog-readiness.md

@@ -0,0 +1,65 @@
+# Backlog Readiness
+
+Use this skill when a backlog item must be evaluated before it is handed to an implementation agent.
+
+## Do Not Use When
+
+- Do not use this skill when the input is still a loose request or idea. Use `backlog-research` first.
+- Do not use this skill when research exists but the work has not been broken into backlog task drafts yet. Use `backlog-planning`.
+- Do not use this skill when the item is already ready and active implementation has started. Use `backlog-execution`.
+
+## Goal
+
+- Decide whether the item is ready, should remain draft until refined, or is blocked.
+- Identify the missing information that would cause execution drift or rework.
+
+## Inputs
+
+- One backlog item that may be close to implementation.
+- Linked research, parent items, dependencies, or surrounding project context when they exist.
+
+## Workflow
+
+1. Read the backlog item, linked research, parent context, and dependency notes.
+2. Evaluate scope, acceptance criteria, dependencies, likely affected systems, and verification plan.
+3. Separate blocking gaps from non-blocking details that can be resolved during implementation.
+4. Record the readiness review in the task markdown, using `.agents/backlog/readiness-checklist.md` as the review format when it exists.
+5. Mark the item `ready` only when the remaining ambiguity is low enough for focused implementation.
+6. If the item is not ready, keep it in draft or blocked state and list the minimum follow-up needed.
+
+## Review Checklist
+
+- Is the scope narrow enough to implement in one focused change?
+- Are the acceptance criteria observable and specific?
+- Are dependencies, blockers, and parent links explicit?
+- Does the item point to the right research or surrounding context?
+- Are the likely files, systems, or interfaces named?
+- Is there a realistic verification plan?
+- Are there unresolved decisions that should be answered before coding starts?
+
+## Output
+
+Record a short readiness review in the backlog item itself, keeping the task file as the source of truth:
+
+- `Verdict`: `ready`, `draft`, or `blocked`.
+- `What is solid`: the parts of the item that are already implementation-safe.
+- `Gaps`: the missing information or weak assumptions.
+- `Required follow-up`: the minimum changes needed before execution.
+
+## Verification
+
+- Confirm the review is based on the actual task file and any linked research, not on chat assumptions alone.
+- Confirm the required follow-up is specific enough that another agent can make the item ready without guessing.
+- Confirm the verdict matches the backlog workflow: only `ready` items should be handed to implementation.
+
+## Next Step
+
+- Hand `ready` items to `backlog-execution`.
+- Route `draft` items back through planning or clarification work.
+- Keep `blocked` items out of execution until the blocker is resolved.
+
+## Rules
+
+- Be strict about ambiguity that would create wasted coding effort.
+- Do not ask for perfect detail when the missing information is non-blocking.
+- Prefer concrete fixes to generic feedback.

package/dist/backlog-research.md

@@ -0,0 +1,56 @@
+# Backlog Research
+
+Use this skill when the agent receives an idea for a feature or project that is not implementation-ready yet.
+
+## Do Not Use When
+
+- Do not use this skill when research already exists and the next step is to create backlog items. Use `backlog-planning` instead.
+- Do not use this skill when a single backlog item is already scoped well enough for readiness review or implementation.
+
+## Goal
+
+- Turn a loose request into durable implementation context stored in the repository.
+- Identify the parts of the codebase, tests, and systems that are likely to be touched.
+- Surface risks, assumptions, and open questions before backlog planning begins.
+
+## Inputs
+
+- A feature idea, product request, bug theme, or project initiative.
+- Optional chat context, existing docs, or links to related code.
+
+## Workflow
+
+1. Restate the goal and identify any blocking ambiguities.
+2. Inspect the repository structure, relevant modules, and nearby tests.
+3. List the files, systems, and interfaces that are likely to change.
+4. Capture constraints, dependencies, migration concerns, and rollout risks.
+5. Propose one or more implementation directions with tradeoffs.
+6. Outline how the work should be verified, including affected existing tests.
+
+## Output
+
+Store the result as a markdown document under `.agents/backlog/research/`, using `.agents/backlog/research-template.md` when it exists.
+
+- `Goal`: what needs to change and why.
+- `Relevant Areas`: files, modules, systems, and integration points.
+- `Implementation Notes`: expected change shape and technical constraints.
+- `Options and Tradeoffs`: viable implementation directions and why one may be preferred.
+- `Test Impact`: existing tests that likely need updates or expansion.
+- `Verification Plan`: automated and manual validation ideas.
+- `Open Questions`: decisions that require user input or product clarification.
+
+## Verification
+
+- Confirm the research names concrete files, modules, or systems whenever they can be identified.
+- Confirm the output distinguishes known facts from assumptions and open questions.
+- Confirm another agent could create backlog items from the document without rereading the whole codebase.
+
+## Next Step
+
+- Hand the research artifact to `backlog-planning` so it can be converted into backlog task drafts.
+
+## Quality Bar
+
+- Do not stop at a high-level summary; name the concrete files and code areas when they can be identified.
+- Call out uncertainty explicitly instead of pretending the repository is clearer than it is.
+- Leave enough detail that another agent can create backlog items without rereading the entire codebase.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { n as initializeProject, t as formatInitializationReport } from "./src-C0-6U5Ro.mjs";
+//#region src/cli.ts
+const HELP_TEXT = `agents-framework
+
+Usage:
+  agents-framework init [--cwd <path>] [--force]
+  agents-framework --help
+
+Commands:
+  init    Detect agent configs, install backlog skills, scaffold backlog structure, and update AGENTS.md/CLAUDE.md.
+
+Options:
+  --cwd <path>     Target project directory. Defaults to the current working directory.
+  --force          Rewrite managed skill files when they already exist.
+  --help           Show this message.
+`;
+async function main(argv) {
+	const parsedArgs = parseArgs(argv);
+	if (parsedArgs.command === "help") {
+		process.stdout.write(HELP_TEXT);
+		return;
+	}
+	const result = await initializeProject({
+		cwd: parsedArgs.cwd,
+		force: parsedArgs.force
+	});
+	process.stdout.write(formatInitializationReport(result));
+}
+function parseArgs(argv) {
+	if (argv.includes("--help") || argv.includes("-h")) return {
+		command: "help",
+		force: false
+	};
+	const args = [...argv];
+	let command = "init";
+	if (args[0] === "init" || args[0] === "help") command = args.shift();
+	if (command === "help") return {
+		command,
+		force: false
+	};
+	let cwd;
+	let force = false;
+	while (args.length > 0) {
+		const argument = args.shift();
+		if (!argument) continue;
+		if (!argument.startsWith("--")) throw new Error(`Unknown argument: ${argument}`);
+		if (argument === "--cwd") {
+			cwd = args.shift();
+			continue;
+		}
+		if (argument === "--force") {
+			force = true;
+			continue;
+		}
+		throw new Error(`Unknown argument: ${argument}`);
+	}
+	return {
+		command,
+		cwd,
+		force
+	};
+}
+main(process.argv.slice(2)).catch((error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`${message}\n`);
+	process.stderr.write("Run `agents-framework --help` for usage.\n");
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+//#region src/constants.d.ts
+declare const AI_FRAMEWORK_BLOCK_START = "<!-- AI_FRAMEWORK:START -->";
+declare const AI_FRAMEWORK_BLOCK_END = "<!-- AI_FRAMEWORK:END -->";
+declare const INSTALL_TARGETS: readonly ["agents", "claude"];
+type InstallationTarget = (typeof INSTALL_TARGETS)[number];
+interface SkillDefinition {
+  slug: string;
+  title: string;
+  summary: string;
+}
+declare const SKILL_DEFINITIONS: readonly SkillDefinition[];
+//#endregion
+//#region src/init.d.ts
+interface InitializeProjectOptions {
+  cwd?: string;
+  force?: boolean;
+}
+interface DetectedConfigs {
+  agentsDir: boolean;
+  claudeDir: boolean;
+  agentsMd: boolean;
+  claudeMd: boolean;
+}
+type FileAction = "created" | "updated" | "skipped";
+interface InstalledSkillResult {
+  path: string;
+  slug: string;
+  status: FileAction;
+  target: InstallationTarget;
+}
+interface InitializeProjectResult {
+  activeTargets: InstallationTarget[];
+  createdFiles: string[];
+  detectedConfigs: DetectedConfigs;
+  installedSkills: InstalledSkillResult[];
+  rootDir: string;
+  updatedFiles: string[];
+  skippedFiles: string[];
+}
+declare function initializeProject(options: InitializeProjectOptions): Promise<InitializeProjectResult>;
+//#endregion
+//#region src/report.d.ts
+declare function formatInitializationReport(result: InitializeProjectResult): string;
+//#endregion
+export { AI_FRAMEWORK_BLOCK_END, AI_FRAMEWORK_BLOCK_START, type DetectedConfigs, type FileAction, INSTALL_TARGETS, type InitializeProjectOptions, type InitializeProjectResult, type InstallationTarget, type InstalledSkillResult, SKILL_DEFINITIONS, type SkillDefinition, formatInitializationReport, initializeProject };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as INSTALL_TARGETS, i as AI_FRAMEWORK_BLOCK_START, n as initializeProject, o as SKILL_DEFINITIONS, r as AI_FRAMEWORK_BLOCK_END, t as formatInitializationReport } from "./src-C0-6U5Ro.mjs";
+export { AI_FRAMEWORK_BLOCK_END, AI_FRAMEWORK_BLOCK_START, INSTALL_TARGETS, SKILL_DEFINITIONS, formatInitializationReport, initializeProject };

package/dist/src-C0-6U5Ro.mjs

@@ -0,0 +1,486 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+//#region src/constants.ts
+const AI_FRAMEWORK_BLOCK_START = "<!-- AI_FRAMEWORK:START -->";
+const AI_FRAMEWORK_BLOCK_END = "<!-- AI_FRAMEWORK:END -->";
+const INSTALL_TARGETS = ["agents", "claude"];
+const TARGET_SKILLS_DIRECTORY = {
+	agents: ".agents/skills",
+	claude: ".claude/skills"
+};
+const SKILL_DEFINITIONS = [
+	{
+		slug: "backlog-research",
+		title: "Backlog Research",
+		summary: "Turn feature or project ideas into concrete repository research and implementation context."
+	},
+	{
+		slug: "backlog-planning",
+		title: "Backlog Planning",
+		summary: "Convert research into ordered backlog items with dependencies and execution boundaries."
+	},
+	{
+		slug: "backlog-readiness",
+		title: "Backlog Readiness",
+		summary: "Evaluate whether a backlog item is ready for execution by an agent."
+	},
+	{
+		slug: "backlog-execution",
+		title: "Backlog Execution",
+		summary: "Execute ready backlog items while keeping status, notes, and validation synchronized."
+	}
+];
+//#endregion
+//#region src/templates/shared.ts
+function toMarkdown(lines) {
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/templates/agents.ts
+function createManagedInstructionsBlock(target) {
+	const title = target === "agents" ? "AGENTS.md" : "CLAUDE.md";
+	const skillsDirectory = TARGET_SKILLS_DIRECTORY[target];
+	const starterSkills = SKILL_DEFINITIONS.map((skill) => `- \`${skill.slug}\``);
+	return toMarkdown([
+		AI_FRAMEWORK_BLOCK_START,
+		"# AI Framework",
+		"",
+		"This repository uses `agents-framework` to keep agent work backlog-driven and repeatable.",
+		"",
+		`- Managed file: \`${title}\``,
+		`- Agent skills: \`${skillsDirectory}\``,
+		"- Shared backlog: `.agents/backlog`",
+		"",
+		"## Required Flow",
+		"",
+		"1. Read `.agents/backlog/README.md` before starting new work.",
+		"2. Pull the highest-priority task from `ready/` into `in-progress/`.",
+		"3. Keep implementation notes, decisions, and verification inside the task markdown.",
+		"4. Move completed work to `done/` only after code, tests, and docs are updated.",
+		"",
+		"## Backlog Routing",
+		"",
+		"- Use `backlog-research` when the request is still a loose idea, project request, or poorly scoped feature.",
+		"- Use `backlog-planning` when research exists and needs to be converted into backlog task drafts.",
+		"- Use `backlog-readiness` when a single backlog item must be reviewed before implementation starts.",
+		"- Use `backlog-execution` when a ready backlog item is being implemented.",
+		"",
+		"## Starter Skills",
+		"",
+		...starterSkills,
+		AI_FRAMEWORK_BLOCK_END
+	]);
+}
+function createInstructionFile(target) {
+	return toMarkdown([
+		`# ${target === "agents" ? "Agent Workspace" : "Claude Workspace"}`,
+		"",
+		"This file is partially managed by `agents-framework`.",
+		"",
+		createManagedInstructionsBlock(target).trimEnd()
+	]);
+}
+//#endregion
+//#region src/templates/backlog.ts
+function createBacklogReadme() {
+	return toMarkdown([
+		"# Agent Backlog",
+		"",
+		"Use this backlog to turn project requests into auditable markdown tasks for the agent.",
+		"",
+		"## Directories",
+		"",
+		"- `research/`: durable research artifacts for ideas that are still being clarified before planning.",
+		"- `draft/`: task drafts created during planning before readiness review is complete.",
+		"- `blocked/`: task drafts or ready items that cannot move forward until an external blocker is resolved.",
+		"- `inbox/`: raw requests and notes that still need scope refinement.",
+		"- `ready/`: well-scoped tasks with acceptance criteria and known dependencies.",
+		"- `in-progress/`: the single task or small batch currently being executed.",
+		"- `done/`: completed tasks with verification notes and links to the delivered change.",
+		"",
+		"## Task Lifecycle",
+		"",
+		"1. Capture new requests in `inbox/` as soon as they appear.",
+		"2. Write a research artifact in `research/` using `research-template.md` when the request is still ambiguous or cross-cutting.",
+		"3. Rewrite the research or request into one or more task drafts in `draft/` using `task-template.md`.",
+		"4. Review each draft with `readiness-checklist.md` before moving it into `ready/`.",
+		"5. Keep under-specified work in `draft/` and move blocked work into `blocked/` until the blocker is resolved.",
+		"6. Move a ready task into `in-progress/` when work actually starts.",
+		"7. Record decisions, risks, links, and verification in the same task file while implementing.",
+		"8. Move the task into `done/` after code, tests, and documentation are in sync.",
+		"",
+		"## Shared Templates",
+		"",
+		"- `research-template.md`: shape a durable research artifact before planning.",
+		"- `task-template.md`: define backlog task drafts and ready-to-execute tasks.",
+		"- `readiness-checklist.md`: review whether a task is specific enough for implementation.",
+		"",
+		"## Naming",
+		"",
+		"Use stable file names such as `AF-001-initialize-cli.md` so backlog history stays easy to follow."
+	]);
+}
+function createResearchTemplate() {
+	return toMarkdown([
+		"# AF-RSCH-000 Research Title",
+		"",
+		"## Goal",
+		"",
+		"- What needs to change?",
+		"- Why does this matter now?",
+		"",
+		"## Relevant Areas",
+		"",
+		"- Files, modules, systems, and integration points that likely need review or changes",
+		"",
+		"## Implementation Notes",
+		"",
+		"- Constraints:",
+		"- Dependencies:",
+		"- Risks:",
+		"",
+		"## Options and Tradeoffs",
+		"",
+		"- Option A:",
+		"- Option B:",
+		"",
+		"## Test Impact",
+		"",
+		"- Existing tests likely affected:",
+		"- New coverage likely needed:",
+		"",
+		"## Verification Plan",
+		"",
+		"- Automated checks:",
+		"- Manual checks:",
+		"",
+		"## Open Questions",
+		"",
+		"-"
+	]);
+}
+function createReadinessChecklistTemplate() {
+	return toMarkdown([
+		"# Readiness Checklist",
+		"",
+		"Use this checklist when deciding whether a backlog item can move into `ready/` for implementation.",
+		"",
+		"## Verdict",
+		"",
+		"- `ready`",
+		"- `draft`",
+		"- `blocked`",
+		"",
+		"## What Is Solid",
+		"",
+		"-",
+		"",
+		"## Gaps",
+		"",
+		"-",
+		"",
+		"## Required Follow-up",
+		"",
+		"-",
+		"",
+		"## Checklist",
+		"",
+		"- [ ] Scope is narrow enough for one focused implementation pass",
+		"- [ ] Acceptance criteria are observable and specific",
+		"- [ ] Dependencies, blockers, and parent links are explicit",
+		"- [ ] Relevant files, systems, or interfaces are named",
+		"- [ ] Linked research or surrounding context is sufficient",
+		"- [ ] Verification plan is realistic for the change"
+	]);
+}
+function createTaskTemplate() {
+	return toMarkdown([
+		"# AF-000 Task Title",
+		"",
+		"## Context",
+		"",
+		"- Why does this work matter now?",
+		"- What user or system problem does it solve?",
+		"",
+		"## Scope",
+		"",
+		"- In scope:",
+		"- Out of scope:",
+		"",
+		"## Acceptance Criteria",
+		"",
+		"- [ ]",
+		"- [ ]",
+		"",
+		"## Implementation Notes",
+		"",
+		"- Constraints:",
+		"- Dependencies:",
+		"- Relevant files or systems:",
+		"",
+		"## Verification",
+		"",
+		"- [ ] Tests updated or added",
+		"- [ ] Docs updated if behavior changed",
+		"- [ ] Manual validation recorded",
+		"",
+		"## Links",
+		"",
+		"- Research:",
+		"- Related tasks:",
+		"",
+		"## Decision Log",
+		"",
+		"-"
+	]);
+}
+//#endregion
+//#region src/templates/skills/index.ts
+const skillTemplateFiles = {
+	"backlog-research": "backlog-research.md",
+	"backlog-planning": "backlog-planning.md",
+	"backlog-readiness": "backlog-readiness.md",
+	"backlog-execution": "backlog-execution.md"
+};
+const templateCache = /* @__PURE__ */ new Map();
+function createSkillContent(slug) {
+	const fileName = skillTemplateFiles[slug];
+	if (!fileName) throw new Error(`Unknown skill slug: ${slug}`);
+	const cachedContent = templateCache.get(fileName);
+	if (cachedContent) return cachedContent;
+	const content = readFileSync(new URL(`./${fileName}`, import.meta.url), "utf8");
+	templateCache.set(fileName, content);
+	return content;
+}
+//#endregion
+//#region src/init.ts
+async function initializeProject(options) {
+	const rootDir = resolve(options.cwd ?? process.cwd());
+	const force = options.force ?? false;
+	const detectedConfigs = await detectConfigs(rootDir);
+	const activeTargets = determineActiveTargets(detectedConfigs);
+	const result = {
+		activeTargets,
+		detectedConfigs,
+		rootDir,
+		installedSkills: [],
+		createdFiles: [],
+		updatedFiles: [],
+		skippedFiles: []
+	};
+	const backlogRoot = join(rootDir, ".agents", "backlog");
+	const managedFiles = [
+		{
+			filePath: join(backlogRoot, "README.md"),
+			content: createBacklogReadme()
+		},
+		{
+			filePath: join(backlogRoot, "task-template.md"),
+			content: createTaskTemplate()
+		},
+		{
+			filePath: join(backlogRoot, "research-template.md"),
+			content: createResearchTemplate()
+		},
+		{
+			filePath: join(backlogRoot, "readiness-checklist.md"),
+			content: createReadinessChecklistTemplate()
+		},
+		{
+			filePath: join(backlogRoot, "research", ".gitkeep"),
+			content: ""
+		},
+		{
+			filePath: join(backlogRoot, "draft", ".gitkeep"),
+			content: ""
+		},
+		{
+			filePath: join(backlogRoot, "blocked", ".gitkeep"),
+			content: ""
+		},
+		{
+			filePath: join(backlogRoot, "inbox", ".gitkeep"),
+			content: ""
+		},
+		{
+			filePath: join(backlogRoot, "ready", ".gitkeep"),
+			content: ""
+		},
+		{
+			filePath: join(backlogRoot, "in-progress", ".gitkeep"),
+			content: ""
+		},
+		{
+			filePath: join(backlogRoot, "done", ".gitkeep"),
+			content: ""
+		}
+	];
+	for (const file of managedFiles) await writeManagedFile(file.filePath, file.content, {
+		force,
+		result,
+		rootDir
+	});
+	for (const target of activeTargets) {
+		const skillsRoot = join(rootDir, TARGET_SKILLS_DIRECTORY[target]);
+		for (const skill of SKILL_DEFINITIONS) {
+			const skillPath = join(skillsRoot, skill.slug, "SKILL.md");
+			const status = await writeManagedFile(skillPath, createSkillContent(skill.slug), {
+				force,
+				result,
+				rootDir
+			});
+			result.installedSkills.push({
+				path: toRelativePath(rootDir, skillPath),
+				slug: skill.slug,
+				status,
+				target
+			});
+		}
+		await upsertInstructionFile(join(rootDir, target === "agents" ? "AGENTS.md" : "CLAUDE.md"), target, {
+			result,
+			rootDir
+		});
+	}
+	return result;
+}
+async function writeManagedFile(filePath, content, context) {
+	await mkdir(dirname(filePath), { recursive: true });
+	const normalizedContent = ensureTrailingNewline(content);
+	const relativePath = toRelativePath(context.rootDir, filePath);
+	if (!await fileExists(filePath)) {
+		await writeFile(filePath, normalizedContent, "utf8");
+		recordFileAction(context.result, "created", relativePath);
+		return "created";
+	}
+	const currentContent = await readFile(filePath, "utf8");
+	if (!context.force) {
+		recordFileAction(context.result, "skipped", relativePath);
+		return "skipped";
+	}
+	if (currentContent === normalizedContent) {
+		recordFileAction(context.result, "skipped", relativePath);
+		return "skipped";
+	}
+	await writeFile(filePath, normalizedContent, "utf8");
+	recordFileAction(context.result, "updated", relativePath);
+	return "updated";
+}
+async function upsertInstructionFile(filePath, target, context) {
+	await mkdir(dirname(filePath), { recursive: true });
+	const relativePath = toRelativePath(context.rootDir, filePath);
+	const nextBlock = createManagedInstructionsBlock(target).trim();
+	if (!await fileExists(filePath)) {
+		await writeFile(filePath, createInstructionFile(target), "utf8");
+		recordFileAction(context.result, "created", relativePath);
+		return;
+	}
+	const currentContent = await readFile(filePath, "utf8");
+	const nextContent = ensureTrailingNewline(upsertManagedBlock(currentContent, nextBlock));
+	if (nextContent === currentContent) {
+		recordFileAction(context.result, "skipped", relativePath);
+		return;
+	}
+	await writeFile(filePath, nextContent, "utf8");
+	recordFileAction(context.result, "updated", relativePath);
+}
+function upsertManagedBlock(currentContent, nextBlock) {
+	const blockPattern = new RegExp(`${escapeForRegExp(AI_FRAMEWORK_BLOCK_START)}[\\s\\S]*?${escapeForRegExp(AI_FRAMEWORK_BLOCK_END)}`, "m");
+	if (blockPattern.test(currentContent)) return currentContent.replace(blockPattern, nextBlock);
+	return `${currentContent.trimEnd()}\n\n${nextBlock}\n`;
+}
+function ensureTrailingNewline(content) {
+	return content.endsWith("\n") ? content : `${content}\n`;
+}
+function toRelativePath(rootDir, targetPath) {
+	return relative(rootDir, targetPath) || targetPath;
+}
+function escapeForRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function fileExists(filePath) {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function detectConfigs(rootDir) {
+	const [agentsDir, claudeDir, agentsMd, claudeMd] = await Promise.all([
+		fileExists(join(rootDir, ".agents")),
+		fileExists(join(rootDir, ".claude")),
+		fileExists(join(rootDir, "AGENTS.md")),
+		fileExists(join(rootDir, "CLAUDE.md"))
+	]);
+	return {
+		agentsDir,
+		claudeDir,
+		agentsMd,
+		claudeMd
+	};
+}
+function determineActiveTargets(detectedConfigs) {
+	const activeTargets = INSTALL_TARGETS.filter((target) => {
+		if (target === "agents") return detectedConfigs.agentsDir || detectedConfigs.agentsMd;
+		return detectedConfigs.claudeDir || detectedConfigs.claudeMd;
+	});
+	return activeTargets.length > 0 ? activeTargets : [...INSTALL_TARGETS];
+}
+function recordFileAction(result, action, relativePath) {
+	if (action === "created") {
+		result.createdFiles.push(relativePath);
+		return;
+	}
+	if (action === "updated") {
+		result.updatedFiles.push(relativePath);
+		return;
+	}
+	result.skippedFiles.push(relativePath);
+}
+//#endregion
+//#region src/report.ts
+function formatInitializationReport(result) {
+	return `${[
+		`Initialized agents-framework in ${result.rootDir}`,
+		"",
+		"Detected configs:",
+		...formatDetectedConfigs(result.detectedConfigs),
+		"",
+		"Active targets:",
+		...formatValues(result.activeTargets),
+		"",
+		"Installed backlog skills:",
+		...formatInstalledSkills(result),
+		"",
+		"Created files:",
+		...formatValues(result.createdFiles),
+		"",
+		"Updated files:",
+		...formatValues(result.updatedFiles),
+		"",
+		"Skipped files:",
+		...formatValues(result.skippedFiles)
+	].join("\n")}\n`;
+}
+function formatDetectedConfigs(detectedConfigs) {
+	return [
+		`- .agents: ${formatPresence(detectedConfigs.agentsDir)}`,
+		`- .claude: ${formatPresence(detectedConfigs.claudeDir)}`,
+		`- AGENTS.md: ${formatPresence(detectedConfigs.agentsMd)}`,
+		`- CLAUDE.md: ${formatPresence(detectedConfigs.claudeMd)}`
+	];
+}
+function formatInstalledSkills(result) {
+	if (result.installedSkills.length === 0) return ["- none"];
+	return result.installedSkills.map((skill) => `- ${skill.target}: ${skill.slug} (${skill.status}) -> ${skill.path}`);
+}
+function formatValues(values) {
+	if (values.length === 0) return ["- none"];
+	return values.map((value) => `- ${value}`);
+}
+function formatPresence(value) {
+	return value ? "found" : "missing";
+}
+//#endregion
+export { INSTALL_TARGETS as a, AI_FRAMEWORK_BLOCK_START as i, initializeProject as n, SKILL_DEFINITIONS as o, AI_FRAMEWORK_BLOCK_END as r, formatInitializationReport as t };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@spotsccc/agents-framework",
+  "version": "0.1.0",
+  "description": "CLI for scaffolding agent operating conventions, backlog workflow, and starter skills.",
+  "keywords": [
+    "agents",
+    "ai",
+    "backlog",
+    "claude-code",
+    "cli",
+    "codex",
+    "scaffolding"
+  ],
+  "homepage": "https://github.com/spotsccc/agents/tree/master/apps/agents-framework#readme",
+  "bugs": {
+    "url": "https://github.com/spotsccc/agents/issues"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spotsccc/agents.git",
+    "directory": "apps/agents-framework"
+  },
+  "bin": {
+    "agents-framework": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./cli": "./dist/cli.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "check": "vp check",
+    "test": "vp test",
+    "typecheck": "vp check --no-fmt --no-lint",
+    "prepublishOnly": "vp pack"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "@typescript/native-preview": "7.0.0-dev.20260309.1",
+    "bumpp": "^10.4.1",
+    "typescript": "^5.9.3",
+    "vite-plus": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}