backlog.md 0.1.0 → 0.1.1

package/src/guidelines/.cursorrules.md

@@ -1,82 +0,0 @@
-# AI Agent Guidelines
-
-*How to collaborate on Backlog.md–driven projects*
-
----
-
-## 1. Source of Truth
-- Tasks live under **`.backlog/tasks/`** (drafts under **`.backlog/drafts/`**).
-- Every implementation decision starts with reading the corresponding Markdown task file.
-
-## 2. Typical Workflow
-
-```bash
-# 1 Identify work
-backlog task list --status "To Do"
-
-# 2 Read details
-backlog task view 42
-
-# 3 Start work: assign yourself & move column
-backlog task edit 42 -a @ai-bot -s "In Progress"
-
-# 4 Break work down if needed
-backlog task create "Refactor DB layer" --parent 42 -a @ai-bot
-
-# 5 Complete and mark Done
-backlog task edit 42 -s Done
-```
-
-## 3. Definition of Done (DOD)
-
-A task is **Done** only when **all** of the following hold:
-
-1. **Acceptance criteria** checklist in the task file is fully checked.  
-2. **Automated tests** (unit + integration) cover new logic and CI passes.  
-3. **Static analysis**: linter & formatter succeed (when available).  
-4. **Documentation**:  
-   - Docs updated.  
-   - Task file appended with a `## Implementation Notes` section summarising approach, trade‑offs and follow‑ups.  
-5. **Review**: code reviewed.  
-6. **Task hygiene**: status set to **Done** via CLI.  
-7. **No regressions**: performance, security and licence checks green.
-
-## 4. Recommended Task Anatomy
-
-```markdown
-# task‑42 - Add GraphQL resolver
-
-## Description
-Short, imperative explanation of the work.
-
-## Acceptance Criteria
-- [ ] Resolver returns correct data for happy path
-- [ ] Error response matches REST
-- [ ] P95 latency ≤ 50 ms under 100 RPS
-
-## Implementation Notes (only added after working on the task)
-*Created by @ai-bot on 2025‑06‑13*
-
-- Added `src/graphql/resolvers/user.ts`
-- Considered DataLoader but deferred
-- Follow‑up: integrate cache layer
-```
-
-## 5. Handy CLI Commands
-
-| Purpose | Command |
-|---------|---------|
-| Create task | `backlog task create "Add OAuth"`                    |
-| Create sub task | `backlog task create --parent 14 "Add Google auth"`                    |
-| List tasks  | `backlog task list`                                  |
-| View detail | `backlog task 7`                                     |
-| Edit        | `backlog task edit 7 -a @sara -l auth,backend`       |
-| Archive     | `backlog task archive 7`                             |
-| Draft flow  | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
-| Demote to draft| `backlog task demote <id>` |
-
-## 6. Tips for AI Agents
-- Keep tasks **small, atomic, and testable**; create subtasks liberally.  
-- Prefer **idempotent** changes so reruns remain safe.  
-- Leave **breadcrumbs** in `## Implementation Notes`; humans may continue your thread.  
-- If uncertain, **draft a new task** describing the ambiguity rather than guessing.  

package/src/guidelines/AGENTS.md

@@ -1,82 +0,0 @@
-# AI Agent Guidelines
-
-*How to collaborate on Backlog.md–driven projects*
-
----
-
-## 1. Source of Truth
-- Tasks live under **`.backlog/tasks/`** (drafts under **`.backlog/drafts/`**).
-- Every implementation decision starts with reading the corresponding Markdown task file.
-
-## 2. Typical Workflow
-
-```bash
-# 1 Identify work
-backlog task list --status "To Do"
-
-# 2 Read details
-backlog task view 42
-
-# 3 Start work: assign yourself & move column
-backlog task edit 42 -a @ai-bot -s "In Progress"
-
-# 4 Break work down if needed
-backlog task create "Refactor DB layer" --parent 42 -a @ai-bot
-
-# 5 Complete and mark Done
-backlog task edit 42 -s Done
-```
-
-## 3. Definition of Done (DOD)
-
-A task is **Done** only when **all** of the following hold:
-
-1. **Acceptance criteria** checklist in the task file is fully checked.  
-2. **Automated tests** (unit + integration) cover new logic and CI passes.  
-3. **Static analysis**: linter & formatter succeed (when available).  
-4. **Documentation**:  
-   - Docs updated.  
-   - Task file appended with a `## Implementation Notes` section summarising approach, trade‑offs and follow‑ups.  
-5. **Review**: code reviewed.  
-6. **Task hygiene**: status set to **Done** via CLI.  
-7. **No regressions**: performance, security and licence checks green.
-
-## 4. Recommended Task Anatomy
-
-```markdown
-# task‑42 - Add GraphQL resolver
-
-## Description
-Short, imperative explanation of the work.
-
-## Acceptance Criteria
-- [ ] Resolver returns correct data for happy path
-- [ ] Error response matches REST
-- [ ] P95 latency ≤ 50 ms under 100 RPS
-
-## Implementation Notes (only added after working on the task)
-*Created by @ai-bot on 2025‑06‑13*
-
-- Added `src/graphql/resolvers/user.ts`
-- Considered DataLoader but deferred
-- Follow‑up: integrate cache layer
-```
-
-## 5. Handy CLI Commands
-
-| Purpose | Command |
-|---------|---------|
-| Create task | `backlog task create "Add OAuth"`                    |
-| Create sub task | `backlog task create --parent 14 "Add Google auth"`                    |
-| List tasks  | `backlog task list`                                  |
-| View detail | `backlog task 7`                                     |
-| Edit        | `backlog task edit 7 -a @sara -l auth,backend`       |
-| Archive     | `backlog task archive 7`                             |
-| Draft flow  | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
-| Demote to draft| `backlog task demote <id>` |
-
-## 6. Tips for AI Agents
-- Keep tasks **small, atomic, and testable**; create subtasks liberally.  
-- Prefer **idempotent** changes so reruns remain safe.  
-- Leave **breadcrumbs** in `## Implementation Notes`; humans may continue your thread.  
-- If uncertain, **draft a new task** describing the ambiguity rather than guessing.  

package/src/guidelines/CLAUDE.md

@@ -1,82 +0,0 @@
-# AI Agent Guidelines
-
-*How to collaborate on Backlog.md–driven projects*
-
----
-
-## 1. Source of Truth
-- Tasks live under **`.backlog/tasks/`** (drafts under **`.backlog/drafts/`**).
-- Every implementation decision starts with reading the corresponding Markdown task file.
-
-## 2. Typical Workflow
-
-```bash
-# 1 Identify work
-backlog task list --status "To Do"
-
-# 2 Read details
-backlog task view 42
-
-# 3 Start work: assign yourself & move column
-backlog task edit 42 -a @ai-bot -s "In Progress"
-
-# 4 Break work down if needed
-backlog task create "Refactor DB layer" --parent 42 -a @ai-bot
-
-# 5 Complete and mark Done
-backlog task edit 42 -s Done
-```
-
-## 3. Definition of Done (DOD)
-
-A task is **Done** only when **all** of the following hold:
-
-1. **Acceptance criteria** checklist in the task file is fully checked.  
-2. **Automated tests** (unit + integration) cover new logic and CI passes.  
-3. **Static analysis**: linter & formatter succeed (when available).  
-4. **Documentation**:  
-   - Docs updated.  
-   - Task file appended with a `## Implementation Notes` section summarising approach, trade‑offs and follow‑ups.  
-5. **Review**: code reviewed.  
-6. **Task hygiene**: status set to **Done** via CLI.  
-7. **No regressions**: performance, security and licence checks green.
-
-## 4. Recommended Task Anatomy
-
-```markdown
-# task‑42 - Add GraphQL resolver
-
-## Description
-Short, imperative explanation of the work.
-
-## Acceptance Criteria
-- [ ] Resolver returns correct data for happy path
-- [ ] Error response matches REST
-- [ ] P95 latency ≤ 50 ms under 100 RPS
-
-## Implementation Notes (only added after working on the task)
-*Created by @ai-bot on 2025‑06‑13*
-
-- Added `src/graphql/resolvers/user.ts`
-- Considered DataLoader but deferred
-- Follow‑up: integrate cache layer
-```
-
-## 5. Handy CLI Commands
-
-| Purpose | Command |
-|---------|---------|
-| Create task | `backlog task create "Add OAuth"`                    |
-| Create sub task | `backlog task create --parent 14 "Add Google auth"`                    |
-| List tasks  | `backlog task list`                                  |
-| View detail | `backlog task 7`                                     |
-| Edit        | `backlog task edit 7 -a @sara -l auth,backend`       |
-| Archive     | `backlog task archive 7`                             |
-| Draft flow  | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
-| Demote to draft| `backlog task demote <id>` |
-
-## 6. Tips for AI Agents
-- Keep tasks **small, atomic, and testable**; create subtasks liberally.  
-- Prefer **idempotent** changes so reruns remain safe.  
-- Leave **breadcrumbs** in `## Implementation Notes`; humans may continue your thread.  
-- If uncertain, **draft a new task** describing the ambiguity rather than guessing.  

package/src/guidelines/index.ts

@@ -1,7 +0,0 @@
-import CURSOR_GUIDELINES from "./.cursorrules.md";
-import AGENT_GUIDELINES from "./AGENTS.md";
-import CLAUDE_GUIDELINES from "./CLAUDE.md";
-
-const README_GUIDELINES = `## AI Agent Guidelines\n\n${AGENT_GUIDELINES.replace(/^#.*\n/, "")}`;
-
-export { AGENT_GUIDELINES, CLAUDE_GUIDELINES, CURSOR_GUIDELINES, README_GUIDELINES };

package/src/index.ts

@@ -1,30 +0,0 @@
-// Types
-export * from "./types/index.ts";
-
-// Constants
-export * from "./constants/index.ts";
-
-// Markdown operations
-export * from "./markdown/parser.ts";
-export * from "./markdown/serializer.ts";
-
-// File system operations
-export { FileSystem } from "./file-system/operations.ts";
-
-// Git operations
-export {
-	GitOperations,
-	isGitRepository,
-	initializeGitRepository,
-} from "./git/operations.ts";
-
-// Core entry point
-export { Core } from "./core/backlog.ts";
-
-// Kanban board utilities
-export { generateKanbanBoard, exportKanbanBoardToFile } from "./board.ts";
-export {
-	addAgentInstructions,
-	type AgentInstructionFile,
-	_loadAgentGuideline,
-} from "./agent-instructions.ts";

package/src/markdown/parser.ts

@@ -1,145 +0,0 @@
-import matter from "gray-matter";
-import type { DecisionLog, Document, ParsedMarkdown, Task } from "../types/index.ts";
-
-function preprocessFrontmatter(frontmatter: string): string {
-	return frontmatter
-		.split("\n")
-		.map((line) => {
-			// Handle both assignee and reporter fields that start with @
-			const match = line.match(/^(\s*(?:assignee|reporter):\s*)(.*)$/);
-			if (!match) return line;
-
-			const [, prefix, raw] = match;
-			const value = raw.trim();
-
-			if (
-				value &&
-				!value.startsWith("[") &&
-				!value.startsWith("'") &&
-				!value.startsWith('"') &&
-				!value.startsWith("-")
-			) {
-				return `${prefix}"${value.replace(/"/g, '\\"')}"`;
-			}
-			return line;
-		})
-		.join("\n");
-}
-
-function normalizeDate(value: unknown): string {
-	if (!value) return "";
-	if (value instanceof Date) {
-		return value.toISOString().slice(0, 10);
-	}
-	const str = String(value)
-		.trim()
-		.replace(/^['"]|['"]$/g, "");
-	if (!str) return "";
-	let match: RegExpMatchArray | null = str.match(/^(\d{4})-(\d{2})-(\d{2})$/);
-	if (match) {
-		return `${match[1]}-${match[2]}-${match[3]}`;
-	}
-	match = str.match(/^(\d{2})-(\d{2})-(\d{2})$/);
-	if (match) {
-		const [day, month, year] = match.slice(1);
-		return `20${year}-${month}-${day}`;
-	}
-	match = str.match(/^(\d{2})\/(\d{2})\/(\d{2})$/);
-	if (match) {
-		const [day, month, year] = match.slice(1);
-		return `20${year}-${month}-${day}`;
-	}
-	match = str.match(/^(\d{2})\.(\d{2})\.(\d{2})$/);
-	if (match) {
-		const [day, month, year] = match.slice(1);
-		return `20${year}-${month}-${day}`;
-	}
-	return str;
-}
-
-export function parseMarkdown(content: string): ParsedMarkdown {
-	const fmRegex = /^---\n([\s\S]*?)\n---/;
-	const match = content.match(fmRegex);
-	let toParse = content;
-
-	if (match) {
-		const processed = preprocessFrontmatter(match[1]);
-		toParse = content.replace(fmRegex, `---\n${processed}\n---`);
-	}
-
-	const parsed = matter(toParse);
-	return {
-		frontmatter: parsed.data,
-		content: parsed.content.trim(),
-	};
-}
-
-export function parseTask(content: string): Task {
-	const { frontmatter, content: description } = parseMarkdown(content);
-
-	return {
-		id: String(frontmatter.id || ""),
-		title: String(frontmatter.title || ""),
-		status: String(frontmatter.status || ""),
-		assignee: Array.isArray(frontmatter.assignee)
-			? frontmatter.assignee.map(String)
-			: frontmatter.assignee
-				? [String(frontmatter.assignee)]
-				: [],
-		reporter: frontmatter.reporter ? String(frontmatter.reporter) : undefined,
-		createdDate: normalizeDate(frontmatter.created_date),
-		updatedDate: frontmatter.updated_date ? normalizeDate(frontmatter.updated_date) : undefined,
-		labels: Array.isArray(frontmatter.labels) ? frontmatter.labels.map(String) : [],
-		milestone: frontmatter.milestone ? String(frontmatter.milestone) : undefined,
-		dependencies: Array.isArray(frontmatter.dependencies) ? frontmatter.dependencies.map(String) : [],
-		description: description,
-		acceptanceCriteria: extractAcceptanceCriteria(description),
-		parentTaskId: frontmatter.parent_task_id ? String(frontmatter.parent_task_id) : undefined,
-		subtasks: Array.isArray(frontmatter.subtasks) ? frontmatter.subtasks.map(String) : undefined,
-	};
-}
-
-export function parseDecisionLog(content: string): DecisionLog {
-	const { frontmatter, content: body } = parseMarkdown(content);
-
-	return {
-		id: String(frontmatter.id || ""),
-		title: String(frontmatter.title || ""),
-		date: normalizeDate(frontmatter.date),
-		status: String(frontmatter.status || "proposed") as DecisionLog["status"],
-		context: extractSection(body, "Context") || "",
-		decision: extractSection(body, "Decision") || "",
-		consequences: extractSection(body, "Consequences") || "",
-		alternatives: extractSection(body, "Alternatives"),
-	};
-}
-
-export function parseDocument(content: string): Document {
-	const { frontmatter, content: body } = parseMarkdown(content);
-
-	return {
-		id: String(frontmatter.id || ""),
-		title: String(frontmatter.title || ""),
-		type: String(frontmatter.type || "other") as Document["type"],
-		createdDate: normalizeDate(frontmatter.created_date),
-		updatedDate: frontmatter.updated_date ? normalizeDate(frontmatter.updated_date) : undefined,
-		content: body,
-		tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : undefined,
-	};
-}
-
-function extractAcceptanceCriteria(content: string): string[] {
-	const criteriaSection = extractSection(content, "Acceptance Criteria");
-	if (!criteriaSection) return [];
-
-	return criteriaSection
-		.split("\n")
-		.filter((line) => line.trim().startsWith("- [ ]") || line.trim().startsWith("- [x]"))
-		.map((line) => line.trim().replace(/^- \[[ x]\] /, ""));
-}
-
-function extractSection(content: string, sectionTitle: string): string | undefined {
-	const regex = new RegExp(`## ${sectionTitle}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`, "i");
-	const match = content.match(regex);
-	return match?.[1]?.trim();
-}

package/src/markdown/serializer.ts

@@ -1,71 +0,0 @@
-import matter from "gray-matter";
-import type { DecisionLog, Document, Task } from "../types/index.ts";
-
-export function serializeTask(task: Task): string {
-	const frontmatter = {
-		id: task.id,
-		title: task.title,
-		status: task.status,
-		assignee: task.assignee,
-		...(task.reporter && { reporter: task.reporter }),
-		created_date: task.createdDate,
-		...(task.updatedDate && { updated_date: task.updatedDate }),
-		labels: task.labels,
-		...(task.milestone && { milestone: task.milestone }),
-		dependencies: task.dependencies,
-		...(task.parentTaskId && { parent_task_id: task.parentTaskId }),
-		...(task.subtasks && task.subtasks.length > 0 && { subtasks: task.subtasks }),
-	};
-
-	const serialized = matter.stringify(task.description, frontmatter);
-	// Ensure there's a blank line between frontmatter and content
-	return serialized.replace(/^(---\n(?:.*\n)*?---)\n(?!$)/, "$1\n\n");
-}
-
-export function serializeDecisionLog(decision: DecisionLog): string {
-	const frontmatter = {
-		id: decision.id,
-		title: decision.title,
-		date: decision.date,
-		status: decision.status,
-	};
-
-	let content = `## Context\n\n${decision.context}\n\n`;
-	content += `## Decision\n\n${decision.decision}\n\n`;
-	content += `## Consequences\n\n${decision.consequences}`;
-
-	if (decision.alternatives) {
-		content += `\n\n## Alternatives\n\n${decision.alternatives}`;
-	}
-
-	return matter.stringify(content, frontmatter);
-}
-
-export function serializeDocument(document: Document): string {
-	const frontmatter = {
-		id: document.id,
-		title: document.title,
-		type: document.type,
-		created_date: document.createdDate,
-		...(document.updatedDate && { updated_date: document.updatedDate }),
-		...(document.tags && document.tags.length > 0 && { tags: document.tags }),
-	};
-
-	return matter.stringify(document.content, frontmatter);
-}
-
-export function updateTaskAcceptanceCriteria(content: string, criteria: string[]): string {
-	// Find if there's already an Acceptance Criteria section
-	const criteriaRegex = /## Acceptance Criteria\s*\n([\s\S]*?)(?=\n## |$)/i;
-	const match = content.match(criteriaRegex);
-
-	const newCriteria = criteria.map((criterion) => `- [ ] ${criterion}`).join("\n");
-	const newSection = `## Acceptance Criteria\n\n${newCriteria}`;
-
-	if (match) {
-		// Replace existing section
-		return content.replace(criteriaRegex, newSection);
-	}
-	// Add new section at the end
-	return `${content}\n\n${newSection}`;
-}

package/src/test/agent-instructions.test.ts

@@ -1,62 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { mkdir, rm } from "node:fs/promises";
-import { join } from "node:path";
-import {
-	AGENT_GUIDELINES,
-	CLAUDE_GUIDELINES,
-	CURSOR_GUIDELINES,
-	README_GUIDELINES,
-	addAgentInstructions,
-} from "../index.ts";
-import { _loadAgentGuideline } from "../index.ts";
-
-const TEST_DIR = join(process.cwd(), "test-agents");
-
-describe("addAgentInstructions", () => {
-	beforeEach(async () => {
-		await rm(TEST_DIR, { recursive: true, force: true });
-		await mkdir(TEST_DIR, { recursive: true });
-	});
-
-	afterEach(async () => {
-		await rm(TEST_DIR, { recursive: true, force: true });
-	});
-
-	it("creates guideline files when none exist", async () => {
-		await addAgentInstructions(TEST_DIR);
-		const agents = await Bun.file(join(TEST_DIR, "AGENTS.md")).text();
-		const claude = await Bun.file(join(TEST_DIR, "CLAUDE.md")).text();
-		const cursor = await Bun.file(join(TEST_DIR, ".cursorrules")).text();
-		expect(agents).toBe(await _loadAgentGuideline(AGENT_GUIDELINES));
-		expect(claude).toBe(await _loadAgentGuideline(CLAUDE_GUIDELINES));
-		expect(cursor).toBe(await _loadAgentGuideline(CURSOR_GUIDELINES));
-	});
-
-	it("appends guideline files when they already exist", async () => {
-		await Bun.write(join(TEST_DIR, "AGENTS.md"), "Existing\n");
-		await addAgentInstructions(TEST_DIR);
-		const agents = await Bun.file(join(TEST_DIR, "AGENTS.md")).text();
-		expect(agents.startsWith("Existing\n")).toBe(true);
-		expect(agents.trimEnd()).toBe(`Existing\n${await _loadAgentGuideline(AGENT_GUIDELINES)}`.trimEnd());
-	});
-
-	it("creates only selected files", async () => {
-		await addAgentInstructions(TEST_DIR, undefined, ["AGENTS.md", "readme.md"]);
-
-		const agentsExists = await Bun.file(join(TEST_DIR, "AGENTS.md")).exists();
-		const claudeExists = await Bun.file(join(TEST_DIR, "CLAUDE.md")).exists();
-		const cursorExists = await Bun.file(join(TEST_DIR, ".cursorrules")).exists();
-		const readme = await Bun.file(join(TEST_DIR, "readme.md")).text();
-
-		expect(agentsExists).toBe(true);
-		expect(claudeExists).toBe(false);
-		expect(cursorExists).toBe(false);
-		expect(readme.trim()).toBe((await _loadAgentGuideline(README_GUIDELINES)).trim());
-	});
-
-	it("loads guideline content from file paths", async () => {
-		const pathGuideline = join(__dirname, "../guidelines/AGENTS.md");
-		const content = await _loadAgentGuideline(pathGuideline);
-		expect(content).toContain("AI Agent Guidelines");
-	});
-});