thomas-agentkit 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# AgentKit CLI
+
+AgentKit CLI bootstraps AI-agent-ready repositories.
+
+It installs reusable instructions, planning templates, review docs, design system rules, and workflow guidance for developers using Codex, Cursor, GitHub Copilot, Claude Code, and similar coding agents.
+
+AgentKit is not an AI agent. It is a small scaffolding tool for making repositories easier and safer to work on with AI-assisted development.
+
+## Usage
+
+Install templates into the current directory:
+
+```bash
+npx thomas-agentkit init
+```
+
+Install into another directory:
+
+```bash
+npx thomas-agentkit init ./my-project
+```
+
+Preview changes without writing files:
+
+```bash
+npx thomas-agentkit init --dry-run
+```
+
+Overwrite existing files:
+
+```bash
+npx thomas-agentkit init --force
+```
+
+Use the optional interactive flow:
+
+```bash
+npx thomas-agentkit init --interactive
+```
+
+List bundled templates:
+
+```bash
+npx thomas-agentkit --list
+```
+
+## Installed Files
+
+AgentKit copies these bundled files into the target project:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `CODE-QUALITY.md`
+- `DESIGN-SYSTEM.md`
+- `IMPLEMENTATION-BRIEF-TEMPLATE.md`
+- `PRD-TEMPLATE.md`
+- `WORKFLOWS.md`
+- `.cursor/rules/agentkit.md`
+- `.github/copilot-instructions.md`
+- `.github/pull_request_template.md`
+
+Existing files are skipped by default so local edits are preserved. Use `--force` when you intentionally want to refresh files from the bundled package version.
+
+## CLI Reference
+
+```text
+agentkit init [target] [--force] [--dry-run] [--interactive] [--yes]
+agentkit --list
+agentkit --help
+agentkit --version
+```
+
+Options:
+
+- `--force`: overwrite existing files
+- `--dry-run`: print planned changes without writing files
+- `-i, --interactive`: prompt for install options
+- `-y, --yes`: accept defaults for non-interactive runs
+- `--list`: list bundled template files
+- `-h, --help`: show help
+- `-v, --version`: show package version
+
+## Local Development
+
+```bash
+npm install
+npm run dev -- init ./tmp-demo --dry-run
+npm run build
+npm test
+```
+
+The npm package is `thomas-agentkit`. The installed CLI command is `agentkit`, backed by the compiled TypeScript entrypoint at `dist/cli.js`.
+
+## Philosophy
+
+AgentKit should stay:
+
+- simple
+- practical
+- easy to inspect
+- easy to modify
+- safe by default
+- useful immediately
+- not overengineered

package/dist/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { confirm, isCancel, text } from "@clack/prompts";
+import { Command } from "commander";
+import { constants as fsConstants } from "node:fs";
+import { access, copyFile, mkdir, readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const templatesDir = path.join(packageRoot, "templates");
+const packageJsonPath = path.join(packageRoot, "package.json");
+async function exists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPackageVersion() {
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return packageJson.version ?? "0.0.0";
+}
+async function getTemplateFiles(dir = templatesDir, base = templatesDir) {
+    const dirStat = await stat(dir);
+    if (!dirStat.isDirectory()) {
+        throw new Error(`Bundled templates directory not found: ${templatesDir}`);
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const absolutePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            return getTemplateFiles(absolutePath, base);
+        }
+        if (!entry.isFile()) {
+            return [];
+        }
+        return [path.relative(base, absolutePath).split(path.sep).join("/")];
+    }));
+    return files.flat().sort();
+}
+async function installTemplates(targetArg, options) {
+    const targetDir = path.resolve(process.cwd(), targetArg || ".");
+    const files = await getTemplateFiles();
+    const created = [];
+    const skipped = [];
+    if (!options.dryRun) {
+        await mkdir(targetDir, { recursive: true });
+    }
+    for (const file of files) {
+        const source = path.join(templatesDir, file);
+        const destination = path.join(targetDir, file);
+        const destinationExists = await exists(destination);
+        if (destinationExists && !options.force) {
+            skipped.push(file);
+            continue;
+        }
+        created.push(file);
+        if (!options.dryRun) {
+            await mkdir(path.dirname(destination), { recursive: true });
+            await copyFile(source, destination);
+        }
+    }
+    return { targetDir, created, skipped };
+}
+function printInstallResult(result, dryRun = false) {
+    const action = dryRun ? "Would install" : "Installed";
+    console.log(`${action} AgentKit files in ${result.targetDir}`);
+    if (result.created.length > 0) {
+        console.log(`${dryRun ? "Would create" : "Created"}: ${result.created.join(", ")}`);
+    }
+    if (result.skipped.length > 0) {
+        console.log(`Skipped existing: ${result.skipped.join(", ")}`);
+        console.log("Use --force to overwrite existing files.");
+    }
+    if (result.created.length === 0 && result.skipped.length === 0) {
+        console.log("No bundled templates found.");
+    }
+}
+async function resolveInteractiveTarget(target, options) {
+    if (!options.interactive) {
+        return target;
+    }
+    const targetResponse = await text({
+        message: "Where should AgentKit install templates?",
+        placeholder: target || ".",
+        defaultValue: target || ".",
+    });
+    if (isCancel(targetResponse)) {
+        process.exit(130);
+    }
+    const forceResponse = await confirm({
+        message: "Overwrite existing files?",
+        initialValue: Boolean(options.force),
+    });
+    if (isCancel(forceResponse)) {
+        process.exit(130);
+    }
+    options.force = forceResponse;
+    return targetResponse || ".";
+}
+async function main() {
+    if (process.argv.slice(2).includes("--list")) {
+        const files = await getTemplateFiles();
+        for (const file of files) {
+            console.log(file);
+        }
+        return;
+    }
+    const program = new Command();
+    program
+        .name("agentkit")
+        .description("Bootstrap AI-agent-ready repository docs and workflow templates.")
+        .version(await readPackageVersion(), "-v, --version")
+        .option("--list", "list bundled template files")
+        .addHelpText("after", `
+
+Examples:
+  agentkit init
+  agentkit init ./my-project --dry-run
+  agentkit --list`);
+    program
+        .command("init")
+        .description("install AgentKit templates into a project")
+        .argument("[target]", "target project directory", ".")
+        .option("--force", "overwrite existing files")
+        .option("--dry-run", "print planned changes without writing files")
+        .option("-i, --interactive", "prompt for install options")
+        .option("-y, --yes", "accept defaults for non-interactive runs")
+        .action(async (target, options) => {
+        const resolvedTarget = await resolveInteractiveTarget(target, options);
+        const result = await installTemplates(resolvedTarget, options);
+        printInstallResult(result, Boolean(options.dryRun));
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "thomas-agentkit",
+  "version": "0.1.0",
+  "description": "Install AI-agent-ready development templates into a project.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agentkit": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/.cursor/rules/agentkit.md

@@ -0,0 +1,26 @@
+# Cursor AgentKit Rules
+
+Use these rules with Cursor agents and composer workflows.
+
+## Default Behavior
+
+- Read `AGENTS.md` before implementation.
+- Read `DESIGN-SYSTEM.md` before UI, styling, layout, navigation, or component work.
+- Read `CODE-QUALITY.md` before review or refactor work.
+- Create or update an implementation brief for complex work.
+
+## Implementation Rules
+
+- Prefer the smallest complete solution.
+- Reuse existing components, utilities, and patterns.
+- Keep diffs focused and reviewable.
+- Avoid speculative abstractions and dependency bloat.
+- Do not change foundational theme, schema, or architecture without explicit approval.
+
+## Handoff
+
+Always summarize:
+
+- Files or areas changed.
+- Checks run.
+- Known risks or follow-up work.

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,25 @@
+# GitHub Copilot Instructions
+
+Follow the repository rules in `AGENTS.md`, `CODE-QUALITY.md`, and `DESIGN-SYSTEM.md`.
+
+## Coding Style
+
+- Prefer simple, maintainable, production-friendly code.
+- Match existing project patterns.
+- Keep changes small and explicit.
+- Avoid adding dependencies unless the benefit is clear.
+- Do not hardcode design tokens, colors, or font families in UI code.
+
+## Before Suggesting Code
+
+- Inspect nearby code and reuse existing utilities or components.
+- Preserve public APIs unless the task requires a change.
+- Include validation at external boundaries.
+- Include tests when behavior changes.
+
+## Avoid
+
+- Speculative abstractions.
+- Broad rewrites for narrow requests.
+- Unrelated formatting churn.
+- Placeholder logic that looks production-ready but is incomplete.

package/templates/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+# Summary
+
+- [What changed?]
+- [Why?]
+
+## Checks
+
+- [ ] Tests run or intentionally skipped
+- [ ] Lint/build checks run or intentionally skipped
+- [ ] Docs updated if behavior changed
+- [ ] No unrelated formatting or refactor churn
+
+## Risk
+
+[Known risks, limitations, or rollout notes.]
+
+## Screenshots / Demo
+
+[Add screenshots, recordings, or notes for UI changes.]

package/templates/AGENTS.md

@@ -0,0 +1,149 @@
+# [Project Name] Agent Guide
+
+## Purpose
+
+This file gives coding agents the project rules they need to work safely and consistently.
+
+[Project Name] is [short project description]. Agents should optimize for fast iteration, low complexity, and production-ready delivery.
+
+## Guidelines
+
+- Act like a high-performing senior engineer. Be concise, direct, decisive, and execution-focused.
+- Solve problems with simple, maintainable, production-friendly solutions.
+- Prefer low-complexity code that is easy to read, debug, and modify.
+- Prefer the smallest path that fully satisfies the requirement.
+- Do not overengineer. Do not introduce heavy abstractions, extra layers, broad fallbacks, or large dependencies for small features.
+- Keep implementations clean, APIs small, behavior explicit, and naming clear.
+- Avoid cleverness unless it clearly improves the outcome.
+- Write code that another strong engineer can quickly understand, safely extend, and confidently ship.
+- Treat user edits as intentional. Do not overwrite or revert work you did not make.
+
+## Do Not
+
+- Do not add edge-case logic for scenarios outside the current requirements.
+- Do not create new components, utilities, or abstractions before checking existing patterns.
+- Do not introduce new dependencies without a clear production benefit.
+- Do not make broad theme, schema, architecture, or formatting changes without explicit approval.
+- Do not run destructive git commands unless explicitly asked.
+
+## Maintainability
+
+Long-term maintainability is a core priority. Keep code direct and easy to change.
+
+Extract shared logic when duplication is real or immediately likely, but do not create speculative abstractions. Do not be afraid to improve existing code when it helps the task, but avoid unrelated refactors.
+
+## Before Coding
+
+Before making meaningful code changes:
+
+1. Check whether the task is linked to an issue in [issue tracker, e.g. Linear or GitHub Issues].
+2. For non-trivial work without an issue, ask whether one should be created before implementation.
+3. Create or switch to an appropriate branch:
+   - Prefer the branch generated by the issue tracker when available.
+   - Otherwise create a clear branch name, such as `feature/bookmark-dedupe` or `fix/auth-redirect`.
+4. Identify the smallest complete solution that satisfies the task.
+5. If the task touches UI, layout, styling, navigation, or components, read `[design system path, e.g. docs/design-system.md]`.
+6. If the task touches framework-specific or backend-specific code, read the local guidance for that system first.
+7. Inspect existing patterns before adding new ones.
+8. For complex or multi-file work, create a short PRD or implementation brief in `[briefs path, e.g. docs/briefs]` before implementation.
+
+Tiny fixes do not need a branch-and-brief ceremony unless the project owner asks for it.
+
+For complex work, the brief should include:
+
+- Problem
+- Scope
+- Out of scope
+- Acceptance criteria
+- Implementation plan
+- Files likely to change
+- Risks
+- Manual QA steps
+
+## During Coding
+
+While implementing:
+
+- Keep the diff small and reviewable.
+- Prefer modifying existing patterns over inventing new ones.
+- Avoid unrelated formatting churn.
+- Keep behavior explicit.
+- Add validation where external input enters the system.
+- Follow `[design system path]` for UI work.
+- Use semantic styling tokens instead of hardcoded colors or fonts.
+- Preserve the project's established density, layout, and interaction patterns.
+- Add loading, empty, error, disabled, and focus states where relevant.
+- Add or update tests when touching pure logic, parsing, data transforms, search, AI output handling, or bug fixes.
+- Preserve existing UX and styling unless the task asks for changes.
+
+## Before Finishing
+
+Before marking work complete:
+
+1. Re-read the original task and acceptance criteria.
+2. Confirm the implementation satisfies the requested scope.
+3. Run the relevant checks:
+   - `[test command, e.g. npm test]`
+   - `[lint command, e.g. npm run lint]`
+   - `[build/check command, e.g. npm run build]` for larger changes
+4. Review the diff for unrelated changes.
+5. Confirm no unnecessary dependencies, schema changes, theme changes, or broad refactors were introduced.
+6. Provide a clear summary of the changes made.
+7. Mention:
+   - Files or areas changed
+   - Checks run
+   - Known risks or limitations
+   - Follow-up work, if any
+
+## Working Style
+
+- Be concise, direct, and execution-focused.
+- Prefer the smallest production-ready solution that fully meets the requirement.
+- Keep code explicit, maintainable, and easy to modify.
+- Avoid speculative abstractions, edge-case overengineering, and dependency bloat.
+- Improve nearby code when helpful, but avoid unrelated refactors.
+- Use existing UI primitives from `[UI component library or path]` before creating custom UI.
+- Do not create reusable custom components unless the task actually needs them.
+- Do not change global color tokens, theme colors, or foundational layout rules without explicit approval.
+
+## Project Commands
+
+Replace these examples with the project's real commands:
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the local development server |
+| `npm test` | Run tests |
+| `npm run lint` | Run lint checks |
+| `npm run build` | Build the project |
+
+Remove commands that do not apply.
+
+## Environment
+
+Document required environment variables here:
+
+- `[ENV_VAR_NAME]`: [description]
+
+Never commit API keys, tokens, private keys, or local `.env` values. Keep secrets in environment variables or the project-approved secret store.
+
+## Stack
+
+Document the real stack for this project:
+
+- [Primary framework]
+- [Language/runtime]
+- [Backend/data layer]
+- [Styling system]
+- [Test tools]
+- [Lint/format tools]
+
+## Optional Framework Rules
+
+Add project-specific rules here when a framework or backend has important local guidance.
+
+Examples:
+
+- Always read generated backend/framework guidance before editing generated or platform-specific code.
+- Follow local generated patterns over generic assumptions.
+- Keep schemas, validators, and API boundaries strict and explicit.

package/templates/CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+## Purpose
+
+Project guidance for Claude-based coding and agent workflows.
+
+## Local Commands
+
+Replace these examples with the project’s real commands:
+
+```bash
+npm install
+npm test
+npm run build
+npm run lint
+```
+
+## Coding Standards
+
+- Keep changes focused on the requested behavior.
+- Prefer clear names and direct control flow.
+- Avoid new abstractions until duplication or complexity justifies them.
+- Preserve existing public interfaces unless the task requires a change.
+- Update nearby documentation when behavior or setup changes.
+
+## Agent Development
+
+- Document each agent’s goal, inputs, outputs, tools, and permission boundaries.
+- Keep prompts and tool schemas versioned with the code that depends on them.
+- Make failure modes explicit: retries, timeouts, partial results, and user-facing errors.
+- Use deterministic tests for core orchestration logic.
+
+## Review And Verification
+
+- Run the narrowest relevant test command first.
+- For UI changes, verify responsive behavior and obvious accessibility states.
+- For agent changes, test success, tool failure, invalid input, and timeout paths.
+- Summarize verification results in the final handoff.
+
+## Secrets
+
+- Use environment variables for local credentials.
+- Do not paste secrets into prompts, logs, fixtures, or committed files.
+- Provide `.env.example` entries for required variables without real values.

package/templates/CODE-QUALITY.md

@@ -0,0 +1,62 @@
+# Code Quality Guide
+
+## Purpose
+
+This guide defines the baseline quality bar for changes in this repository.
+
+Agents and contributors should optimize for code that is simple, readable, testable, and safe to modify.
+
+## Principles
+
+- Prefer small, explicit changes over broad rewrites.
+- Keep public APIs narrow and intentional.
+- Use clear names and direct control flow.
+- Avoid speculative abstractions and dependency bloat.
+- Match existing project patterns before introducing new ones.
+- Make failure modes explicit at system boundaries.
+
+## Review Checklist
+
+- The change solves the stated problem and does not expand scope unexpectedly.
+- The diff is small enough to review confidently.
+- No unrelated formatting churn or broad refactors were introduced.
+- New behavior has relevant tests or a clear reason tests were not added.
+- External inputs are validated at boundaries.
+- Errors are actionable and do not leak secrets.
+- User-facing copy is clear and specific.
+- UI changes include loading, empty, error, disabled, and focus states where relevant.
+
+## Testing Expectations
+
+Run the narrowest useful checks first, then broaden verification for larger changes.
+
+Document project commands here:
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+Remove commands that do not apply.
+
+## Dependency Policy
+
+Add a dependency only when it clearly reduces real complexity or improves correctness. Prefer existing project utilities and platform APIs for small features.
+
+Before adding a dependency, confirm:
+
+- The package is actively maintained.
+- The API surface is small enough for the need.
+- The behavior would be meaningfully harder or riskier to implement locally.
+- The dependency does not create avoidable runtime, security, or bundle-size risk.
+
+## Handoff Standard
+
+Every completed change should include:
+
+- What changed.
+- Why it changed.
+- What checks were run.
+- Known risks or limitations.
+- Follow-up work, if any.

package/templates/DESIGN-SYSTEM.md

@@ -0,0 +1,229 @@
+# [Project Name] Design System - Linear-Inspired Foundations
+
+This design system codifies the visual and interaction principles for [Project Name].
+
+It is the default source of truth for app shell layout, navigation, lists, controls, and page chrome in this repository.
+
+All colors, typography families, and radii must be consumed through semantic tokens in `[theme stylesheet path, e.g. src/styles.css]` or a dedicated theme stylesheet imported there. Components must not hardcode literal color values or font family names.
+
+## 1) Surface And Color
+
+### Philosophy
+
+The interface is a single continuous canvas. Separation comes from spacing, typography, and occasional structural seams, not stacked containers.
+
+### Token Roles
+
+Define semantic CSS custom properties and map them to the project's theme tokens:
+
+- `--background`: app canvas
+- `--foreground`: primary text
+- `--muted-foreground`: secondary/meta text
+- `--border`: structural seams
+- `--card`: elevated container for dialogs/popovers only
+- `--popover`: overlay surfaces
+- `--accent`: subtle hover/active in content areas
+- `--sidebar`: sidebar canvas
+- `--sidebar-accent`: hover/active in sidebar
+- `--primary`: brand and primary CTA
+- `--destructive`: danger actions
+- `--ring`: focus ring
+
+### Rules
+
+- No layered cards for routine content.
+- No decorative gradients on product surfaces.
+- Use one accent color, `--primary`, for brand and primary actions.
+- Prefer spacing over background differentiation.
+- Keep all colors tokenized and theme-ready for light and dark modes.
+
+## 2) Typography
+
+### Families
+
+- Interface text: `font-sans` backed by `--font-sans`.
+- Code, IDs, and timestamps: `font-mono` backed by `--font-mono`.
+
+Do not reference literal font families in component files.
+
+### Scale
+
+- Page heading: `text-xl`, `font-semibold`
+- Section heading: `text-base`, `font-semibold`
+- Body / row label: `text-xs`, `font-normal` to `font-medium`
+- Meta / secondary: `text-[11px]`, `font-normal`
+- Nav section label: `text-[11px] uppercase tracking-wide`, `font-medium`
+- Tiny helper: `text-[10px]`, `font-normal`
+
+### Rules
+
+- Headlines are quiet and utilitarian.
+- Keep line height tight with `leading-tight` or `leading-snug` for dense UI.
+- Reserve uppercase for nav labels and compact metadata.
+
+## 3) Navigation
+
+### Structure
+
+1. Header row: identity, search, and create action.
+2. Primary links.
+3. Collapsible grouped links.
+4. Lightweight footer affordance for help or docs.
+
+### Item Styling
+
+- Default: `text-xs`, muted foreground.
+- Hover: subtle `sidebar-accent` background.
+- Active: full-width pill, medium weight.
+- Icon size: 12px.
+- Nav pill baseline: `rounded-full h-7 px-2.5`.
+
+### Collapse Behavior
+
+- Expanded width: `15rem` or 240px.
+- Collapsed width: `3rem` or 48px, icon-only with tooltip.
+- Mobile: sheet/drawer using expanded width.
+- Keyboard shortcut: support the project's standard sidebar toggle shortcut, e.g. `Cmd+B`.
+
+## 4) Layout Regions
+
+### App Shell
+
+- Sidebar: fixed left, full viewport height, right seam border.
+- Content: `flex-1 min-w-0`, same background canvas.
+- Optional inspector: right panel, `22rem` to `28rem`, collapsible.
+
+### Common Page Patterns
+
+- List workspace: toolbar plus scrollable list.
+- Detail view: breadcrumbs/title plus body and optional inspector.
+- Editor split: left rail plus center editor.
+- Settings split: nav plus forms.
+
+### Toolbar Strip
+
+- Height: `h-10` to `h-12`.
+- Bottom seam: `border-b border-border/50`.
+- No separate background block.
+
+## 5) Interactive Elements
+
+### Buttons
+
+- Primary: solid `primary`.
+- Secondary: neutral fill.
+- Ghost: transparent with subtle hover fill.
+- Destructive: `destructive` only for dangerous confirms.
+- Icon-only: `size-8`, ghost, tooltip.
+
+Rules:
+
+- Default radius uses the tokenized radius scale.
+- No shadows on standard buttons.
+- Primary buttons are intentionally sparse.
+
+### Inputs
+
+- Compact defaults: `h-8`; dense contexts: `h-7`.
+- Tokenized input background and border.
+- Visible focus ring: `ring-2 ring-ring`.
+- Labels above fields. Do not use floating labels by default.
+
+### Menus / Popovers / Dialogs
+
+- Tokenized `popover` surface and subtle border.
+- Tight typography: `text-xs`.
+- Compact spacing.
+- Dialog actions align right: secondary then primary.
+
+## 6) Lists And Data
+
+### Row Anatomy
+
+- Compact, single-line by default.
+- Hover uses subtle accent fill.
+- Selected row uses stronger accent fill and medium weight.
+- Avoid per-row borders; separate by spacing and padding rhythm.
+
+### Grouping And Tables
+
+- Group labels are muted; children are indented.
+- Table headers use uppercase compact meta style.
+- No zebra striping or heavy gridlines.
+
+## 7) Status And Feedback
+
+- Status: small dots or icons with semantic meaning.
+- Loading: skeletons for content, spinners only for inline actions.
+- Toasts: non-intrusive, auto-dismiss.
+- Empty states: icon, short message, and optional single CTA.
+
+## 8) Motion
+
+- Motion confirms state changes; it is never decorative.
+- Micro interactions: about 150ms.
+- Layout shifts: about 200-250ms.
+- Preferred easing: `cubic-bezier(0.16, 1, 0.3, 1)`.
+- Respect `prefers-reduced-motion` with near-instant transitions.
+
+## 9) Spacing System
+
+Base unit is 4px, using the project's spacing scale.
+
+- `p-1` or 4px: tight internals.
+- `p-2` or 8px: compact section padding.
+- `p-3` or 12px: dense content blocks.
+- `p-4` or 16px: page-level rhythm.
+
+Density guidelines:
+
+- Sidebar: dense, `h-7` rows.
+- Content: moderate, `h-8` to `h-10` rows.
+- Forms/settings: relaxed, `h-10` to `h-12` rows.
+
+## 10) Accessibility
+
+- Full keyboard navigation for all controls.
+- Consistent visible focus styles.
+- Semantic landmarks such as `nav` and `main`.
+- Collapsibles expose `aria-expanded`.
+- Ensure WCAG AA contrast in both themes.
+
+## 11) Anti-Patterns
+
+- Do not wrap normal content in elevated cards.
+- Do not introduce multiple accent colors.
+- Do not add decorative gradients behind core product surfaces.
+- Do not stack multiple competing toolbars.
+- Do not color-code nav icons.
+- Do not hardcode colors or font families in components.
+
+## 12) Applying This System
+
+### Where Values Live
+
+- Theme tokens and base layer: `[theme stylesheet path, e.g. src/styles.css]`.
+- App shell composition: `[route/layout path, e.g. src/routes or app]`.
+- Reusable UI primitives: `[components path, e.g. src/components/ui]`.
+
+### New Component Checklist
+
+1. Sits on canvas, not card-first?
+2. Uses 2-3 text hierarchy levels max?
+3. Has subtle hover and clear active states?
+4. Uses primary color only where needed?
+5. Uses spacing rhythm in 4px increments?
+6. Has complete keyboard and focus behavior?
+7. Uses token-driven colors and fonts?
+8. Works in light and dark themes?
+
+### For Coding Agents
+
+- Read this file before changing UI, layout, navigation, styling, or components.
+- Prefer existing UI primitives and local layout patterns.
+- Do not introduce new visual language without documenting the reason in the implementation brief or PR.
+- Before handoff, check responsive behavior, focus states, text overflow, loading states, empty states, and token usage.
+
+### Working Rule
+
+Default to these principles unless a deliberate exception is documented in a feature-specific spec.

package/templates/IMPLEMENTATION-BRIEF-TEMPLATE.md

@@ -0,0 +1,49 @@
+# Implementation Brief
+
+## Title
+
+[Feature or fix name]
+
+## Problem
+
+[What problem are we solving?]
+
+## Scope
+
+- [In-scope item]
+- [In-scope item]
+
+## Out Of Scope
+
+- [Out-of-scope item]
+- [Out-of-scope item]
+
+## Acceptance Criteria
+
+- [ ] [Concrete scenario passes]
+- [ ] [Concrete scenario passes]
+- [ ] Relevant checks pass.
+
+## Implementation Plan
+
+1. [Step]
+2. [Step]
+3. [Step]
+
+## Files Likely To Change
+
+- `[path]`: [reason]
+- `[path]`: [reason]
+
+## Risks
+
+- [Risk]: [mitigation]
+
+## Manual QA
+
+- [Manual verification step]
+- [Manual verification step]
+
+## Notes
+
+[Useful context, links, or decisions.]

package/templates/PRD-TEMPLATE.md

@@ -0,0 +1,70 @@
+# PRD Template
+
+## Title
+
+[Project or feature name]
+
+## Problem
+
+Describe the user problem, business problem, or technical gap this work addresses.
+
+## Goals
+
+- [Goal 1]
+- [Goal 2]
+
+## Non-Goals
+
+- [Out-of-scope item 1]
+- [Out-of-scope item 2]
+
+## Users
+
+- Primary user:
+- Secondary users:
+- Internal operators or reviewers:
+
+## Requirements
+
+### Functional
+
+- [Required behavior]
+- [Required behavior]
+
+### Non-Functional
+
+- Performance:
+- Reliability:
+- Security:
+- Accessibility:
+- Observability:
+
+## UX Notes
+
+- Primary workflow:
+- Empty state:
+- Error state:
+- Permission or authentication state:
+
+## Technical Notes
+
+- Systems touched:
+- APIs or schemas:
+- Data flow:
+- Migration or compatibility concerns:
+
+## Risks
+
+- [Risk and mitigation]
+- [Risk and mitigation]
+
+## Acceptance Criteria
+
+- [ ] [Concrete scenario passes]
+- [ ] [Concrete scenario passes]
+- [ ] Tests cover success and failure paths.
+
+## Open Questions
+
+- [Question]
+- [Question]

package/templates/WORKFLOWS.md

@@ -0,0 +1,54 @@
+# Project Workflows
+
+## Purpose
+
+This document defines lightweight workflows for planning, implementation, review, and release.
+
+Keep this file practical. Delete sections that do not apply to the project.
+
+## Planning Workflow
+
+Use a PRD for product or user-facing work that needs intent, requirements, and acceptance criteria.
+
+Use an implementation brief for engineering work that is already understood but needs a clear execution plan.
+
+Tiny fixes can skip formal planning when the change is obvious and low risk.
+
+## Branch Workflow
+
+- Prefer an issue-linked branch when available.
+- Use short, descriptive branch names:
+  - `feature/[short-name]`
+  - `fix/[short-name]`
+  - `chore/[short-name]`
+- Keep each branch focused on one coherent change.
+
+## Coding Workflow
+
+1. Read the issue, PRD, or implementation brief.
+2. Inspect existing patterns.
+3. Make the smallest complete change.
+4. Add or update tests where behavior changes.
+5. Run relevant checks.
+6. Review the diff before handoff.
+
+## Review Workflow
+
+Review for correctness first, then maintainability, tests, UX, and style.
+
+Call out:
+
+- Bugs or regressions.
+- Missing validation or error handling.
+- Overly broad abstractions.
+- Missing tests for changed behavior.
+- UI states that are missing or inaccessible.
+
+## Release Workflow
+
+Before release:
+
+- Confirm tests and build pass.
+- Confirm docs match behavior.
+- Confirm environment variables and migrations are documented.
+- Confirm no secrets or local-only files are included.