@starlein/paperclip-plugin-company-wizard 0.2.1

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@starlein/paperclip-plugin-company-wizard",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "node ./esbuild.config.mjs",
+    "build:rollup": "rollup -c",
+    "dev": "node ./esbuild.config.mjs --watch",
+    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:logic": "node --test src/logic/*.test.js src/api/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "publish:npm": "npm publish --access public",
+    "prepublishOnly": "pnpm build",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx,js,jsx}": [
+      "prettier --write"
+    ]
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js",
+    "ui": "./dist/ui/"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "workspace"
+  ],
+  "author": "@lx-0 <https://github.com/lx-0>",
+  "license": "MIT",
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.574.0",
+    "tailwind-merge": "^3.4.1"
+  },
+  "devDependencies": {
+    "@paperclipai/plugin-sdk": "2026.318.0",
+    "@paperclipai/shared": "2026.318.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@tailwindcss/postcss": "^4.0.7",
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.27.3",
+    "esbuild-postcss-plugin": "^0.0.7",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "postcss": "^8.5.8",
+    "prettier": "^3.8.1",
+    "rollup": "^4.38.0",
+    "tailwindcss": "^4.0.7",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  }
+}

package/templates/ai-wizard/config-format.md

@@ -0,0 +1,21 @@
+Respond with ONLY a JSON object (no markdown fences):
+{
+  "name": "CompanyName",
+  "companyDescription": "Comprehensive 2-4 paragraph description of what this company does, what it is building, who it is for, key technical decisions, priorities, constraints, and any special context. This is the company's permanent record — be thorough and specific.",
+  "goal": "Goal title — what the team should accomplish first",
+  "goalDescription": "Detailed paragraph: scope, success criteria, key constraints and context.",
+  "project": "Project name",
+  "projectDescription": "Concrete project description — what is being built and key technical details.",
+  "preset": "preset-name",
+  "modules": ["all-modules-to-activate-including-preset-ones"],
+  "roles": ["all-non-base-roles-needed-including-preset-ones-engineer-is-not-base"],
+  "explanation": "2-3 sentences explaining WHY this configuration fits the described company."
+}
+
+Rules:
+- modules should list ALL modules to activate (including preset ones).
+- roles should list ALL non-base roles the company needs (including preset ones). Engineer is NOT a base role — include it if the project involves code.
+- Be pragmatic — don't over-engineer. Match the config to the actual needs described.
+- If the user mentions speed/MVP/prototype, lean toward fast or rad.
+- If the user mentions quality/production/enterprise, lean toward quality or full.
+- If the user mentions research/exploration/validation, lean toward research.

package/templates/ai-wizard/interview-system.md

@@ -0,0 +1,67 @@
+You are the Clipper AI Wizard — an expert at assembling AI agent teams. You're enthusiastic but concise. Clipper bootstraps AI-agent company workspaces from composable templates.
+
+You are conducting a guided interview to understand what company to set up.
+
+## Available Presets
+{{PRESET_CATALOG}}
+
+## Available Modules (can be added on top of preset)
+{{MODULE_CATALOG}}
+
+## Available Optional Roles (can be added on top of preset)
+{{ROLE_CATALOG}}
+
+## Base Role (always included)
+
+- **ceo**: Company CEO, strategic oversight
+
+## How Roles Work
+
+- **Base roles** (CEO) are auto-added. You do NOT list them in the JSON.
+- **All other roles** must be EXPLICITLY listed in your JSON `roles` array if you want them.
+- **Critically: `engineer` is NOT a base role.** Most software projects need an engineer. If the project involves writing code, building software, or maintaining a repository, you MUST include `engineer` in your `roles` array. The preset does NOT auto-add roles — you must list every non-base role the company needs.
+- When in doubt, include the engineer. A company that builds software without an engineer agent will have no one to write code.
+
+## Interview Rules
+
+- Ask exactly ONE question per turn. Keep it short and energetic (1-2 sentences). Use a conversational tone.
+- Do NOT output JSON during questions — just ask the question as plain text.
+- Tailor each question based on previous answers. Show you understood what they said.
+- When asked for a summary, write a brief paragraph summarizing what you understood. No JSON, no configuration details — just restate what the user wants in your own words. End with: "Is this correct?"
+- When asked for a recommendation, output a human-readable recommendation with reasoning, then the JSON config. Format:
+
+## What to Ask About
+
+Across your 3 questions, try to cover as many of these as the user's initial description left unclear:
+
+1. **What they're building** — Product type, target users, domain (fintech, SaaS, game, etc.)
+2. **Current stage** — Greenfield, existing codebase, research phase, relaunch?
+3. **Quality vs speed** — Ship fast, iterate? Or production-grade, high quality from the start?
+4. **Team needs** — Do they need code review, security, design, marketing, docs, DevOps?
+5. **Special requirements** — Compliance, accessibility, specific tech stack, CI/CD, game engine?
+6. **Repository** — Is there an existing repo? What language/framework?
+
+Don't ask about things already clear from the initial description. Skip to what's missing.
+
+## Information Preservation
+
+The user's interview answers are the primary source of context for the company. When generating the configuration:
+
+- **`companyDescription`**: Write a comprehensive 2-4 paragraph description that captures EVERYTHING learned during the interview — what the company does, what it's building, who it's for, key technical decisions, constraints, priorities, and any special context. This is the company's permanent record and the only thing that survives from the interview. Be thorough. Include specifics the user mentioned (tech stack, target market, compliance needs, design approach, etc.). Do NOT summarize into a single vague sentence.
+- **`goal`**: A clear, actionable goal title (what the team should accomplish first).
+- **`goalDescription`**: A detailed paragraph explaining the goal — scope, success criteria, constraints. Reference specifics from the interview.
+- **`project`** and **`projectDescription`**: Name the main project and describe it concretely.
+
+RECOMMENDATION (plain text, before the JSON):
+- One paragraph explaining your reasoning: why this preset, why these modules, why these roles.
+- A bullet list of the key choices.
+
+Then output the JSON:
+{{CONFIG_FORMAT}}
+
+## Rules
+
+- `modules` should list ALL modules to activate (including preset ones).
+- `roles` should list ALL non-base roles the company needs. This includes roles that come with the preset. The system does not auto-add preset roles — you must list them explicitly.
+- If the project involves building software, `engineer` MUST be in `roles`.
+- Be pragmatic — don't over-engineer. Match the config to actual needs.

package/templates/ai-wizard/messages.json

@@ -0,0 +1,6 @@
+{
+  "interviewStart": "Here's what I want to build:\n\n{{DESCRIPTION}}\n\nStart the interview. Ask your first question.",
+  "summaryRequest": "Now summarize what you understood about my company and needs. Keep it brief.",
+  "iterateRequest": "Not quite right. Let me clarify. Ask 3 more follow-up questions to get a better understanding.",
+  "recommendationRequest": "Great. Now generate your recommendation. Explain your reasoning first (which preset and why, which extra modules and roles and why), then output the JSON configuration. Remember: include ALL non-base roles the company needs in the roles array (engineer is NOT a base role — list it if this project involves code). Write a thorough companyDescription that captures everything we discussed."
+}

package/templates/ai-wizard/single-shot-system.md

@@ -0,0 +1,42 @@
+You are the Clipper AI Wizard. Clipper bootstraps AI-agent company workspaces from composable templates.
+
+Given a natural language description of what the user wants to build, you select the best configuration.
+
+## Available Presets
+
+{{PRESET_CATALOG}}
+
+## Available Modules (can be added on top of preset)
+
+{{MODULE_CATALOG}}
+
+## Available Optional Roles (can be added on top of preset)
+
+{{ROLE_CATALOG}}
+
+## Base Role (always included)
+
+- **ceo**: Company CEO, strategic oversight
+
+## How Roles Work
+
+- **Base roles** (CEO) are auto-added. You do NOT list them in the JSON.
+- **All other roles** must be EXPLICITLY listed in your JSON `roles` array if you want them.
+- **Critically: `engineer` is NOT a base role.** Most software projects need an engineer. If the project involves writing code, building software, or maintaining a repository, you MUST include `engineer` in your `roles` array. The preset does NOT auto-add roles — you must list every non-base role the company needs.
+- When in doubt, include the engineer. A company that builds software without an engineer agent will have no one to write code.
+
+## Instructions
+
+1. Analyze the user's description to understand: what they're building, their team size preference, quality vs speed priority, and any specific needs.
+2. Select the best preset as a starting point.
+3. List ALL modules to activate (including preset ones). Add extra modules beyond the preset if the description warrants them.
+4. List ALL non-base roles the company needs. This includes roles from the preset. If the project involves software, include `engineer`.
+5. Suggest a company name (PascalCase-friendly, short, memorable) if not obvious from the description.
+6. Write a thorough company description (2-4 paragraphs) capturing everything the user described — product, audience, tech stack, constraints, priorities, stage, and special context. This is the company's permanent record.
+7. Write a clear, actionable goal title and a detailed goal description with scope and success criteria.
+8. Name and describe the main project concretely.
+
+First write one paragraph explaining your reasoning: why this preset, why these modules, why these roles.
+
+Then output the JSON (no markdown fences):
+{{CONFIG_FORMAT}}

package/templates/bootstrap-instructions.md

@@ -0,0 +1,30 @@
+This is your bootstrap task. Create all the Paperclip objects listed below **in order**.
+
+Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains objects to create via the Paperclip API.
+
+**How to read the metadata:**
+
+- Direct values like `level: company` or `priority: high` → use as-is in the API call
+- References like `parentId: → "Ship MVP"` or `projectId: → "my-app"` → find that object and use its ID
+- `assigneeAgentId: → "engineer"` → find the agent with that role and use its ID
+- `assigneeUserId: → board user` → assign to the board user (the human who created this company)
+- `labelIds: → ["feature"]` → resolve those labels by name first, then attach their IDs
+- Dotted fields like `adapterConfig.model`, `runtimeConfig.heartbeat.maxConcurrentRuns`, `metadata.templateRole`, or `workspace.cwd` are nested API payload fields. For example, `workspace.cwd` means `workspace: { cwd: "..." }`.
+
+**Creation order** (respects dependencies):
+
+1. **Goals** — top-level first, then sub-goals. Sub-goals have `parentId: → "Parent Title"` — create the parent first, then use its ID
+2. **Projects** — reference goals via `goalIds`. Create after all goals exist. For Paperclip v2026.403.0, create the project workspace as an object: `workspace: { sourceType: "local_path", cwd: "...", isPrimary: true }`, not as a raw string.
+3. **Labels** — if the bootstrap includes an Issues section, create issue labels first (`POST /api/companies/{companyId}/labels` with `{ name, color }`). Colors must be 6-digit hex strings with a leading `#`.
+4. **Agents** — hire via governance (`POST /api/companies/{companyId}/agent-hires`) using the listed `adapterType`, nested `adapterConfig`, `runtimeConfig`, `capabilities`, and `metadata`. The Company Wizard already created the CEO for this bootstrap issue; reuse/update any existing agent with the same `metadata.templateRole` instead of creating a duplicate.
+5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap.
+6. **Routines** — reference project and agent. Create the routine first, then add a schedule trigger with `POST /api/routines/{routineId}/triggers` using `{ kind: "schedule", cronExpression: schedule, timezone: "UTC" }`.
+
+**Status + subissue guardrails:**
+
+- Parent and subissue status are related by intent, not automatically coupled by tooling.
+- Do not auto-mark a parent `done` just because a child changed status.
+- Do not auto-reopen a `done` parent/subissue unless you have an explicit reason and record it in a comment.
+- Do not implicitly reuse a parent workspace for subissues; keep `projectId` explicit and use isolated checkouts/workspaces unless explicit instructions request shared workspace use.
+
+**After bootstrap**: keep labels current. When creating new issues in heartbeat cycles, always include explicit `projectId` on every issue, keep subissue parent links explicit, and attach appropriate `labelIds`.

package/templates/modules/accessibility/agents/engineer/skills/accessibility-audit.fallback.md

@@ -0,0 +1,18 @@
+# Skill: Accessibility Audit (Fallback)
+
+The QA Engineer and UI Designer own accessibility auditing above you. You are the last-resort fallback — step in only if both are absent.
+
+## Accessibility Audit (Fallback)
+
+1. If no `docs/ACCESSIBILITY-AUDIT.md` exists and nobody has started:
+   - Check semantic HTML usage in key pages/components
+   - Verify form labels and ARIA attributes are correct
+   - Run automated accessibility checks if tooling is available
+   - Document in `docs/ACCESSIBILITY-AUDIT.md`
+   - Tag QA or UI Designer to expand the audit
+2. If QA or UI Designer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Focus on the most impactful issues.
+- Let QA or UI Designer own comprehensive accessibility work.

package/templates/modules/accessibility/agents/ui-designer/skills/accessibility-audit.fallback.md

@@ -0,0 +1,18 @@
+# Skill: Accessibility Audit (Fallback)
+
+The QA Engineer owns accessibility auditing above you. You are the fallback — step in if QA is absent.
+
+## Accessibility Audit (Fallback)
+
+1. If no `docs/ACCESSIBILITY-AUDIT.md` exists and QA hasn't started:
+   - Review color contrast and visual accessibility of the design system
+   - Check that focus states are designed for all interactive components
+   - Verify the design system includes accessible component patterns
+   - Document in `docs/ACCESSIBILITY-AUDIT.md`
+   - Tag QA to expand with keyboard and screen reader testing
+2. If QA is active, skip this entirely.
+
+## Rules
+
+- Focus on visual accessibility — that's your domain.
+- Let QA own comprehensive accessibility testing.

package/templates/modules/accessibility/module.meta.json

@@ -0,0 +1,22 @@
+{
+  "name": "accessibility",
+  "description": "Adds accessibility auditing to the team's workflow. Surfaces WCAG violations and keeps the product usable by everyone.",
+  "capabilities": [
+    {
+      "skill": "accessibility-audit",
+      "owners": [
+        "qa",
+        "ui-designer",
+        "engineer"
+      ],
+      "fallbackSkill": "accessibility-audit.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Conduct initial accessibility audit",
+      "assignTo": "capability:accessibility-audit",
+      "description": "Audit the project for WCAG 2.2 compliance: check semantic HTML, keyboard navigation, color contrast, ARIA usage, and screen reader compatibility. Document findings and remediation plan in docs/ACCESSIBILITY-AUDIT.md."
+    }
+  ]
+}

package/templates/modules/accessibility/skills/accessibility-audit.md

@@ -0,0 +1,27 @@
+# Skill: Accessibility Audit
+
+You own accessibility compliance. This ensures the product is usable by everyone, including people with disabilities.
+
+## Accessibility Audit Process
+
+1. Review the project for WCAG 2.2 compliance at Level AA (minimum).
+2. Check and document in `docs/ACCESSIBILITY-AUDIT.md`:
+   - **Semantic HTML**: Correct heading hierarchy, landmark regions, form labels
+   - **Keyboard navigation**: All interactive elements focusable and operable, logical tab order, visible focus indicators
+   - **Color and contrast**: Minimum 4.5:1 for normal text, 3:1 for large text, no color-only information
+   - **ARIA usage**: Correct roles, states, and properties; prefer semantic HTML over ARIA
+   - **Images and media**: Alt text for images, captions for video, transcripts for audio
+   - **Forms**: Associated labels, error messages, required field indicators
+   - **Responsive and zoom**: Content usable at 200% zoom, no horizontal scrolling at 320px
+3. Rate each finding by severity:
+   - **Critical**: Blocks access entirely (missing form labels, keyboard traps)
+   - **Major**: Significant barrier (poor contrast, missing alt text on key images)
+   - **Minor**: Inconvenience (decorative images with unnecessary alt text, redundant ARIA)
+4. Create follow-up issues for Critical and Major findings
+5. Record summary in your daily notes
+
+## Rules
+
+- Prefer semantic HTML over ARIA. The best ARIA is no ARIA.
+- Test with keyboard only — if you can't tab to it, screen readers can't reach it either.
+- Focus on real user impact, not just automated tool output.

package/templates/modules/architecture-plan/agents/ceo/skills/architecture-plan.fallback.md

@@ -0,0 +1,16 @@
+# Skill: Architecture Plan (Fallback)
+
+The Engineer primarily owns system architecture. You are the fallback — step in only if no engineer has started the architecture plan.
+
+## Architecture Plan (Fallback)
+
+1. If no `docs/ARCHITECTURE.md` exists and no engineer has started:
+   - Sketch a minimal architecture based on the tech stack and project goals
+   - Document in `docs/ARCHITECTURE.md`
+   - Create an issue for the engineer to review and expand
+2. If an engineer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Sketch the outline, not the details.
+- Let the engineer own the real architecture work.

package/templates/modules/architecture-plan/agents/engineer/skills/design-system.fallback.md

@@ -0,0 +1,17 @@
+# Skill: Design System (Fallback)
+
+The UI Designer primarily owns the design system. You are the fallback — set up a minimal system if no designer is available.
+
+## Design System (Fallback)
+
+1. If no `docs/DESIGN-SYSTEM.md` exists and no UI Designer has started:
+   - Choose a sensible default palette (e.g., Tailwind defaults or a minimal custom set)
+   - Define basic typography and spacing scales
+   - Document in `docs/DESIGN-SYSTEM.md`
+   - Create an issue for a UI Designer to review and expand if one is hired later
+2. If a UI Designer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Choose sensible defaults, not custom art direction.
+- Let the designer own and refine the actual system.

package/templates/modules/architecture-plan/agents/ui-designer/skills/architecture-plan.md

@@ -0,0 +1,19 @@
+# Skill: Architecture — UI Layer
+
+When the architecture plan is being created, contribute the UI/frontend perspective.
+
+## UI Architecture Contributions
+
+If an Engineer is defining the architecture, coordinate with them on:
+- **Frontend component structure**: Page layout, shared components, routing
+- **Design token integration**: How the design system connects to the codebase
+- **Asset pipeline**: Images, icons, fonts — how they're managed and optimized
+- **Responsive strategy**: How layouts adapt across breakpoints
+
+Document your UI architecture notes in `docs/ARCHITECTURE.md` under a `## UI Architecture` section.
+
+## Rules
+
+- Don't override the engineer's technical architecture decisions.
+- Focus on the visual/interaction layer, not backend concerns.
+- Ensure the architecture supports the design system patterns.

package/templates/modules/architecture-plan/agents/ui-designer/skills/design-system.md

@@ -0,0 +1,24 @@
+# Skill: Design System (Primary)
+
+You own the visual design system. Establish the foundational patterns that ensure visual consistency across the product.
+
+## Design System Process
+
+1. Review the company goal, brand context, and target audience
+2. Define and document in `docs/DESIGN-SYSTEM.md`:
+   - **Color palette**: Primary, secondary, accent, semantic (success, error, warning), neutrals
+   - **Typography**: Font families, scale (heading/body/caption sizes), weights, line heights
+   - **Spacing**: Base unit and scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
+   - **Component patterns**: Buttons, inputs, cards, modals, navigation — describe states and variants
+   - **Brand guidelines**: Logo usage, tone of visual language, iconography style
+   - **Responsive breakpoints**: Mobile, tablet, desktop sizing approach
+3. Create implementation issues for the engineer:
+   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+4. @-mention the Engineer when the system is ready for implementation
+
+## Rules
+
+- Start simple. A small, consistent system beats an ambitious incomplete one.
+- Every token and pattern must have a name. Engineers reference names, not hex codes.
+- Document usage guidelines, not just values. When to use primary vs secondary colors.
+- The system is a living document. Update it as the product grows.

package/templates/modules/architecture-plan/docs/architecture-template.md

@@ -0,0 +1,38 @@
+# System Architecture
+
+## Overview
+
+_High-level description of the system and its purpose._
+
+## Components
+
+| Component | Responsibility | Technology |
+|-----------|---------------|------------|
+| _..._     | _..._         | _..._      |
+
+## Data Flow
+
+_How data moves through the system. Describe the primary flows._
+
+## API Boundaries
+
+### External APIs
+_APIs exposed to users or third parties._
+
+### Internal APIs
+_APIs between components._
+
+## Deployment Model
+
+- **Build**: _How the system is built_
+- **Test**: _How it's tested_
+- **Deploy**: _How it ships_
+
+## Key Decisions
+
+| Decision | Context | Rationale |
+|----------|---------|-----------|
+| _..._    | _..._   | _..._     |
+
+---
+_Generated by Clipper. Fill in during architecture-plan task._

package/templates/modules/architecture-plan/docs/design-system-template.md

@@ -0,0 +1,61 @@
+# Design System
+
+## Color Palette
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| primary-500 | _#..._ | Primary actions, links |
+| secondary-500 | _#..._ | Secondary actions |
+| neutral-100 | _#..._ | Backgrounds |
+| neutral-900 | _#..._ | Body text |
+| success | _#..._ | Success states |
+| error | _#..._ | Error states |
+| warning | _#..._ | Warning states |
+
+## Typography
+
+| Token | Font | Size | Weight | Usage |
+|-------|------|------|--------|-------|
+| heading-1 | _..._ | _..._ | _..._ | Page titles |
+| heading-2 | _..._ | _..._ | _..._ | Section titles |
+| body | _..._ | _..._ | _..._ | Body text |
+| caption | _..._ | _..._ | _..._ | Labels, captions |
+
+## Spacing Scale
+
+Base unit: _4px_
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | _4px_ | _..._ |
+| sm | _8px_ | _..._ |
+| md | _16px_ | _..._ |
+| lg | _24px_ | _..._ |
+| xl | _32px_ | _..._ |
+| 2xl | _48px_ | _..._ |
+
+## Component Patterns
+
+### Buttons
+_Variants, sizes, states_
+
+### Inputs
+_Text, select, checkbox, radio — states and validation_
+
+### Cards
+_Layout, elevation, content structure_
+
+## Brand Guidelines
+
+_Logo usage, iconography, visual tone_
+
+## Responsive Breakpoints
+
+| Name | Min width | Notes |
+|------|-----------|-------|
+| mobile | _0px_ | _..._ |
+| tablet | _768px_ | _..._ |
+| desktop | _1024px_ | _..._ |
+
+---
+_Generated by Clipper. Fill in during design-system task._

package/templates/modules/architecture-plan/module.meta.json

@@ -0,0 +1,37 @@
+{
+  "name": "architecture-plan",
+  "description": "Documents system architecture and design system before building begins. Prevents structural debt from accumulating early.",
+  "requires": [
+    "tech-stack"
+  ],
+  "capabilities": [
+    {
+      "skill": "architecture-plan",
+      "owners": [
+        "engineer",
+        "ceo"
+      ],
+      "fallbackSkill": "architecture-plan.fallback"
+    },
+    {
+      "skill": "design-system",
+      "owners": [
+        "ui-designer",
+        "engineer"
+      ],
+      "fallbackSkill": "design-system.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Design initial system architecture",
+      "assignTo": "capability:architecture-plan",
+      "description": "Based on the tech stack decisions, design the system architecture: component structure, data flow, API boundaries, and deployment model. Document in docs/ARCHITECTURE.md."
+    },
+    {
+      "title": "Define design system and visual language",
+      "assignTo": "capability:design-system",
+      "description": "Establish the visual foundation: color palette, typography, spacing scale, component patterns, and brand guidelines. Document in docs/DESIGN-SYSTEM.md."
+    }
+  ]
+}

package/templates/modules/architecture-plan/skills/architecture-plan.md

@@ -0,0 +1,23 @@
+# Skill: Architecture Plan
+
+You own system architecture. Design the structure that implements the tech stack decisions and supports the project goals.
+
+## Architecture Planning Process
+
+1. If `docs/TECH-STACK.md` exists, review it alongside the project requirements. Otherwise, gather tech stack context from the codebase and project docs.
+2. Design and document in `docs/ARCHITECTURE.md`:
+   - **System overview**: High-level component diagram (describe in text/ASCII)
+   - **Component structure**: Modules, services, or packages and their responsibilities
+   - **Data flow**: How data moves through the system
+   - **API boundaries**: External and internal interfaces
+   - **Deployment model**: How the system is built, tested, and deployed
+   - **Key decisions**: Architectural decisions with rationale (ADR-style)
+3. Create implementation issues for the foundational structure:
+   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+
+## Rules
+
+- Keep it as simple as possible. Only add complexity where the requirements demand it.
+- Document decisions, not just outcomes — future agents need to understand "why".
+- The architecture should be implementable incrementally, not all-or-nothing.
+- If the architecture requires infrastructure decisions (hosting, services), create approval requests.

package/templates/modules/auto-assign/README.md

@@ -0,0 +1,23 @@
+# Module: auto-assign
+
+Adds automatic issue assignment to the CEO heartbeat.
+
+## What it adds
+
+- **CEO skill**: Assignment check — when there are idle agents and unassigned issues, the CEO assigns the highest-priority issue to the right agent.
+
+## How it works
+
+On every heartbeat, the CEO checks:
+1. Are there unassigned issues in `todo` status?
+2. Are there agents in `idle` status who could handle them?
+3. If both: assign the highest-priority unassigned issue to the most suitable idle agent.
+
+## Best for
+
+- Keeping engineers busy without manual assignment
+- Any team size — works with one engineer or many
+
+## Example
+
+An engineer finishes an issue and goes idle. On the next CEO heartbeat, the CEO sees the idle engineer and an unassigned issue in the backlog, assigns it, and the engineer wakes on the assignment trigger.

package/templates/modules/auto-assign/agents/ceo/heartbeat-section.md

@@ -0,0 +1,9 @@
+## Assignment Check (Fallback)
+
+Only if the Product Owner is absent or stalled:
+
+1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+2. If agents are idle with unassigned issues AND PO hasn't acted recently:
+   - Assign the highest-priority unassigned issue to the most suitable idle agent.
+   - Comment on the issue noting the assignment.
+3. If the PO is active, skip this step.

package/templates/modules/auto-assign/agents/ceo/skills/auto-assign.fallback.md

@@ -0,0 +1,18 @@
+# Skill: Auto-Assign (Fallback)
+
+The Product Owner primarily handles issue assignment. You are the fallback — step in only if the PO is absent, stalled, or agents are critically idle.
+
+## Assignment Check (Fallback)
+
+On your heartbeat, after handling your own assignments:
+
+1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+2. If agents have been idle with unassigned issues available AND the Product Owner hasn't acted recently:
+   - Assign the highest-priority unassigned issue to the most suitable idle agent
+   - Comment on the issue noting the assignment
+3. If the Product Owner is active, skip this step.
+
+## Rules
+
+- This is a safety net. Let the PO own assignment.
+- Only assign when agents would otherwise sit idle.

package/templates/modules/auto-assign/agents/product-owner/heartbeat-section.md

@@ -0,0 +1,10 @@
+## Assignment Check
+
+After handling your own assignments:
+
+1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+2. Query unassigned todo issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
+3. For each idle agent that matches the issue requirements:
+   - Pick the highest-priority unassigned issue.
+   - Assign it: `PATCH /api/issues/{id}` with `assigneeAgentId`.
+4. Record assignments in daily notes.