Add support for multi-repository awareness/context

.gitignore

@@ -1 +1,3 @@
 node_modules
+.awos
+.claude

CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Important: Do NOT Run the Installer
+
+**Never run `npx @provectusinc/awos` when contributing to this repository.** That command is for end users setting up AWOS in their own projects.
+
+## What This Repository Is
+
+AWOS (Agentic Workflow Operating System) is a framework for spec-driven development using AI agents. It consists of:
+
+1. **An Installer** (`src/`) - Node.js CLI that copies framework files to user projects
+2. **AI Agent Prompts** (`commands/`, `subagents/`) - Markdown files that define agent behaviors
+3. **Document Templates** (`templates/`) - Structured templates for specifications and planning
+
+## Repository Structure
+
+```
+awos/
+├── index.js              # Entry point (delegates to src/)
+├── src/                  # Installer source code (Node.js)
+│   ├── config/           # Setup configuration and constants
+│   ├── core/             # Main orchestration logic
+│   ├── services/         # File copying and directory creation
+│   ├── migrations/       # Version migration system
+│   └── utils/            # Logging and pattern matching
+├── commands/             # AWOS command prompts (→ .awos/commands/)
+├── templates/            # Document templates (→ .awos/templates/)
+├── subagents/            # Specialized coding agent prompts (→ .awos/subagents/)
+├── claude/               # User customization layer (→ .claude/)
+└── context/              # Created in user projects for specs
+```
+
+## Testing Changes
+
+Test in a separate project directory:
+
+```bash
+# Create/navigate to test project
+cd ~/my-test-project
+
+# Run installer from local clone
+npx /path/to/awos/index.js
+
+# Test with force overwrite
+npx /path/to/awos/index.js --force-overwrite
+
+# Preview changes without applying
+npx /path/to/awos/index.js --dry-run
+```
+
+## Key Architecture Concepts
+
+### File Copy Behavior
+
+Defined in `src/config/setup-config.js`:
+
+- `.awos/` files: Always overwritten (framework internals)
+- `.claude/` files: Only overwritten with `--force-overwrite` (user customizations)
+
+### Migration System
+
+For restructuring files in existing installations:
+
+- Migration files: `src/migrations/NNN-description.json`
+- Preconditions: `require_any`, `require_all`, `skip_if_any`, `error_if_any`
+- Operations: `move`, `copy`, `delete`
+- Version tracked in: `.awos/.migration-version`
+
+### Command Workflow Pattern
+
+Each command prompt follows: ROLE → TASK → INPUTS/OUTPUTS → PROCESS
+
+Sequential workflow: `/awos:product` → `/awos:roadmap` → `/awos:architecture` → `/awos:spec` → `/awos:tech` → `/awos:tasks` → `/awos:implement`
+
+### Agent Delegation Rule
+
+The `/awos:implement` command delegates to subagents - it never writes code directly.
+
+## Code Formatting
+
+```bash
+npx prettier --write .
+```

claude/agents/domain-experts/repo-scanner.md

@@ -0,0 +1,6 @@
+---
+name: repo-scanner
+description: Use this agent to scan repositories and answer questions about their contents. Supports both local filesystem repos and GitHub repos (via MCP). Accepts repo_type (local/github), repo_path, and a question to answer. Iteratively scans files until it can provide a comprehensive answer with references. Always instruct the agent to read the `.awos/subagents/repo-scanner.md` file before proceeding.
+model: haiku
+color: cyan
+---

claude/commands/registry.md

@@ -0,0 +1,5 @@
+---
+description: Manages the multi-repository registry — links related repos for cross-project context.
+---
+
+Refer to the instructions located in this file: .awos/commands/registry.md

commands/architecture.md

@@ -26,14 +26,72 @@ Your task is to manage the architecture file located at `context/product/archite
 # PROCESS
 
 Follow this logic precisely.
+When you need user input on a decision:
 
-### Step 1: Prerequisite Checks
+- Use **AskUserQuestion** tool with clear, clickable options
+- Never present numbered lists requiring manual number entry
+
+### Step 1: Load Cross-Repository Context
+
+1. **Read Registry:** Use the Read tool to check if `context/registry.md` exists.
+   - If it doesn't exist, skip to Step 2 (no error, no message).
+   - If it exists, read and parse its contents to understand:
+     - What repositories are registered (names, types, paths etc.)
+     - Their status (`active` or `stale`)
+     - Relationships and dependencies between repos and this project
+     - AWOS-enabled status and available context
+     - Tech stack information from registry entries
+
+2. **Determine Context Needs:** Based on architecture planning needs, identify which registered repos are relevant:
+   - **Direct dependencies:** Repos this project depends on or will integrate with
+   - **Shared ecosystem:** Repos with tech stack decisions that should be consistent
+   - **Common libraries:** Shared dependencies or internal packages
+   - **API contracts:** Services this project will call or expose to
+   - **Infrastructure patterns:** Deployment, monitoring, or security approaches to align with
+   - **Skip stale repos:** Do not fetch context from repos marked as `stale`
+
+3. **Fetch AWOS Context (if enabled):** For AWOS-enabled repos where deeper architecture context would help:
+
+   Use the Task tool to delegate to the `repo-scanner` subagent. Pass:
+   - `repo_type`: `local` or `github` (from registry entry)
+   - `repo_path`: filesystem path or `owner/repo` (from registry entry)
+   - `question`: "Read the `context/product` directory and summarize the architecture decisions, tech stack, infrastructure choices, and any integration patterns."
+
+   **Note:** Only scan repos that are both AWOS-enabled AND relevant to architecture decisions. Skip repos that are informational only.
+
+4. **Fetch Additional Context (if needed):** If needed more context or clarifying questions:
+
+   Use the Task tool to delegate to the `repo-scanner` subagent. Pass:
+   - `repo_type`: `local` or `github` (from registry entry)
+   - `repo_path`: filesystem path or `owner/repo` (from registry entry)
+   - `question`: clarifying questions or necessary information
+
+   Iterate with scanner until you get all necessary information.**This step can be repeated throughout implementation** whenever the subagent needs additional context about related repos.
+
+5. **Process Results:** Receive repository context from scanner. Organize internally:
+   - Common tech stack patterns across the ecosystem
+   - Shared infrastructure or deployment approaches
+   - API patterns and integration points between repos
+   - Authentication/authorization patterns if applicable
+   - Dependencies that will impact architectural decisions in this project
+   - Constraints or standards that must be followed
+
+6. **Use Context Silently:** Apply this context throughout the conversation to inform architecture suggestions. When recommending technologies:
+   - Prefer consistency with related repos unless there's a strong reason to diverge
+   - Flag when a choice would create integration complexity
+   - Consider shared infrastructure opportunities
+
+**Do NOT display ecosystem summaries to the user. Use the context to make better recommendations.**
+
+---
+
+### Step 2: Prerequisite Checks
 
 - First, check if both `context/product/product-definition.md` and `context/product/roadmap.md` exist.
 - If either file is missing, you must stop immediately. Respond with: "Before we can design the architecture, we need a clear product definition and roadmap. Please run `/awos:product` and `/awos:roadmap` first, then run me again."
 - If both files exist, proceed to the next step.
 
-### Step 2: Mode Detection
+### Step 3: Mode Detection
 
 - Now, check if the file `context/product/architecture.md` exists.
 - If it **does not exist**, proceed to **Scenario 1: Creation Mode**.
@@ -53,7 +111,7 @@ Follow this logic precisely.
     - Example interaction: "For the backend, considering the features in Phase 1, I suggest using **Python with FastAPI** for its development speed and performance. An excellent alternative would be **Node.js with Express** if your team has stronger JavaScript expertise. Which direction feels right for this project?"
     - **Clarify and Confirm:** If the user is unsure, ask clarifying questions about their team's skills, budget, or priorities to help them decide. Do not proceed until the choices for the current section are confirmed.
     - Repeat this collaborative process for all necessary architectural areas (Data, Infrastructure, etc.).
-3.  **Finalize:** Once all sections of the template are filled and confirmed by the user, proceed to **Step 3: Finalization**.
+3.  **Finalize:** Once all sections of the template are filled and confirmed by the user, proceed to **Step 4: Finalization**.
 
 ---
 
@@ -73,11 +131,11 @@ Follow this logic precisely.
 4.  **Consistency Check:**
     - Before saving, perform a quick mental check. Does this change conflict with existing principles or technologies? Does it align with the project's direction?
     - If you spot a potential issue, raise it politely: "Just a thought, adding this new database might increase our operational costs. Is that an acceptable trade-off?"
-5.  **Finalize:** When the user confirms all changes, proceed to **Step 3: Finalization**.
+5.  **Finalize:** When the user confirms all changes, proceed to **Step 4: Finalization**.
 
 ---
 
-### Step 3: Finalization
+### Step 4: Finalization
 
 1.  **Confirm:** State clearly: "Great! I am now saving the architecture document."
 2.  **Save File:** Write the final, complete content to `context/product/architecture.md`.

commands/implement.md

@@ -29,8 +29,70 @@ Your goal is to execute the next available task for a given specification. You w
 # PROCESS
 
 Follow this process precisely.
+When you need user input on a decision:
+
+- Use **AskUserQuestion** tool with clear, clickable options
+- Never present numbered lists requiring manual number entry
+
+### Step 1: Load Cross-Repository Context
+
+1. **Read Registry:** Use the Read tool to check if `context/registry.md` exists.
+   - If it doesn't exist, skip to Step 2 (no error, no message).
+   - If it exists, read and parse its contents to understand:
+     - What repositories are registered (names, types, paths etc.)
+     - Their status (`active` or `stale`)
+     - Relationships and dependencies between repos and this project
+     - AWOS-enabled status and available context
+     - Code patterns, APIs, and implementation approaches from registry entries
+
+2. **Determine Context Needs:** Based on implementation needs, identify which registered repos are relevant:
+   - **Code patterns:** Repos with conventions and patterns to follow for consistency
+   - **API contracts:** Repos with API schemas, endpoints, or clients to integrate with
+   - **Shared types:** Repos with interfaces, models, or DTOs to maintain compatibility
+   - **Dependencies:** Repos with libraries or utilities this implementation will use
+   - **Integration points:** Repos where this code will call or be called by external services
+   - **Skip stale repos:** Do not fetch context from repos marked as `stale`
+
+3. **Fetch AWOS Context (if enabled):** For AWOS-enabled repos that the current task integrates with:
+
+   Use the Task tool to delegate to the `repo-scanner` subagent. Pass:
+   - `repo_type`: `local` or `github` (from registry entry)
+   - `repo_path`: filesystem path or `owner/repo` (from registry entry)
+   - `question`: "Read the `context` directory including `context/product` and `context/spec`. Summarize the architecture, API designs, data models, code patterns, and any integration requirements relevant to implementation."
+
+   **Note:** Only scan repos that are both relevant to the current task AND have integration points. Skip repos that are informational only.
+
+4. **Fetch Additional Context (if needed):** If more context or clarifying questions are needed during implementation:
+
+   Use the Task tool to delegate to the `repo-scanner` subagent. Pass:
+   - `repo_type`: `local` or `github` (from registry entry)
+   - `repo_path`: filesystem path or `owner/repo` (from registry entry)
+   - `question`: specific questions about APIs, types, patterns, or integration details
+
+   Iterate with scanner until you get all necessary information. **This step can be repeated throughout implementation** whenever the subagent needs additional context about related repos.
+
+5. **Process Results:** Receive repository context from scanner. Organize internally:
+   - How to call APIs from dependent repos
+   - Shared types or interfaces to use
+   - Testing approaches used in related repos
+   - Error handling and logging conventions
+   - Authentication/authorization patterns for API calls
+   - Conventions and patterns to follow for consistency
+   - API schemas, endpoints, or clients to integrate with
+   - Interfaces, models, or DTOs to maintain compatibility
+   - Libraries or utilities this implementation will use
+   - Functions or methods this code will call or where this code will be called by external services
+
+6. **Use Context Silently:** When delegating to subagents, include relevant cross-repo context to ensure implementation is compatible with the ecosystem. When making recommendations:
+   - Provide API contract details for integrations
+   - Include shared type definitions for compatibility
+   - Reference coding conventions from related repos
+
+**Do NOT display ecosystem summaries to the user. Implementation stays within current repo (no cross-repo code changes).**
 
-### Step 1: Identify the Target Specification and Task
+---
+
+### Step 2: Identify the Target Specification and Task
 
 1.  **Analyze User Prompt:** First, analyze the `<user_prompt>`. If it specifies a particular spec or task (e.g., "implement the next task for spec 002" or "run the database migration for the profile picture feature"), use that to identify the target spec directory and/or task.
 2.  **Automatic Mode (Default):** If the `<user_prompt>` is empty, you must automatically find the next task to be done.

commands/product.md

@@ -37,26 +37,83 @@ Your primary task is to **fill in** a product definition template using a guided
 # PROCESS
 
 Follow this logic precisely.
+When you need user input on a decision:
 
-### Step 1: Mode Detection
+- Use **AskUserQuestion** tool with clear, clickable options
+- Never present numbered lists requiring manual number entry
+
+### Step 1: Load Cross-Repository Context
+
+1. **Read Registry:** Use the Read tool to check if `context/registry.md` exists.
+   - If it doesn't exist, skip to Step 2 (no error, no message).
+   - If it exists, read and parse its contents to understand:
+     - What repositories are registered (names, types, paths etc.)
+     - Their status (`active` or `stale`)
+     - Relationships and dependencies between repos and this project
+     - AWOS-enabled status and available context
+     - Product vision and roadmap information from registry entries
+
+2. **Determine Context Needs:** Based on product definition needs, identify which registered repos are relevant:
+   - **Product positioning:** Repos with product definitions that inform this project's positioning
+   - **Related functionality:** Repos with features that affect scope decisions
+   - **Target audience overlap:** Repos serving similar or complementary user bases
+   - **Integration points:** Repos this product will integrate with, extend or use
+   - **Dependencies:** Repos that impact target audience or features
+   - **Skip stale repos:** Do not fetch context from repos marked as `stale`
+
+3. **Fetch AWOS Context (if enabled):** For AWOS-enabled repos where deeper product context would help:
+
+   Use the Task tool to delegate to the `repo-scanner` subagent. Pass:
+   - `repo_type`: `local` or `github` (from registry entry)
+   - `repo_path`: filesystem path or `owner/repo` (from registry entry)
+   - `question`: "Read the `context/product` directory and summarize the product vision, target audience, core features, and roadmap phases."
+
+   **Note:** Only scan repos that are both AWOS-enabled AND relevant to product decisions. Skip repos that are informational only.
+
+4. **Fetch Additional Context (if needed):** If needed more context or clarifying questions:
+
+   Use the Task tool to delegate to the `repo-scanner` subagent. Pass:
+   - `repo_type`: `local` or `github` (from registry entry)
+   - `repo_path`: filesystem path or `owner/repo` (from registry entry)
+   - `question`: clarifying questions or necessary information
+
+   Iterate with scanner until you get all necessary information.**This step can be repeated throughout implementation** whenever the subagent needs additional context about related repos.
+
+5. **Process Results:** Receive repository context from scanner. Organize internally:
+   - How this product relates to the ecosystem
+   - Potential overlaps or integrations with other products
+   - Shared target audiences or complementary features
+   - Dependencies that will impact product scope or positioning
+   - Opportunities for differentiation or synergy
+
+6. **Use Context Silently:** Apply this context throughout the conversation to inform product suggestions and decisions. When making recommendations:
+   - Consider how features might integrate with or depend on related repos
+   - Flag potential overlaps with existing products in the ecosystem
+   - Identify opportunities to leverage shared infrastructure or services
+
+**Do NOT display ecosystem summaries to the user. Use the context to make better recommendations.**
+
+---
+
+### Step 2: Mode Detection
 
 First, check if the file `context/product/product-definition.md` exists.
 
-- If it **exists**, proceed to **Step 2A: Update Mode**.
-- If it **does not exist**, proceed to **Step 2B: Creation Mode**.
+- If it **exists**, proceed to **Step 3A: Update Mode**.
+- If it **does not exist**, proceed to **Step 3B: Creation Mode**.
 
 ---
 
-### Step 2A: Update Mode
+### Step 3A: Update Mode
 
 1.  **Acknowledge and Read:** Inform the user you've found an existing definition. Say: "Welcome back! I've found your existing product definition at `context/product/product-definition.md`. Let's update it." Read its contents into your memory.
 2.  **Display Menu:** Ask the user, "**Which section would you like to update?**" and present a numbered list of the main sections from their document.
 3.  **Execute Update:** Once the user chooses a section, jump to the corresponding logic in the "Creation Mode" steps below to ask questions and refine only that part of the document.
-4.  **Loop or Finish:** After updating a section, ask: "Great, I've updated that. Would you like to change another section or are you ready to save?" If they are done, proceed to **Step 3: File Generation**.
+4.  **Loop or Finish:** After updating a section, ask: "Great, I've updated that. Would you like to change another section or are you ready to save?" If they are done, proceed to **Step 4: File Generation**.
 
 ---
 
-### Step 2B: Creation Mode
+### Step 3B: Creation Mode
 
 1.  **Introduction:** Introduce yourself: "Hi, I'm Poe 📝. I'll help you create a clear, high-level product definition by filling out a standard template."
 2.  **Handle Initial Arguments:**
@@ -69,11 +126,11 @@ First, check if the file `context/product/product-definition.md` exists.
     - **Success Metrics:** Ask how they will measure the product's impact on the user.
     - **Core Features & User Journey:** Ask for the 3-5 most important high-level features and a simple user workflow.
     - **Project Boundaries:** Ask what is essential for the first version (In-Scope) and what can wait (Out-of-Scope).
-4.  **Proceed to Finalization:** Once all sections are complete, proceed to **Step 3: File Generation**.
+4.  **Proceed to Finalization:** Once all sections are complete, proceed to **Step 4: File Generation**.
 
 ---
 
-### Step 3: File Generation
+### Step 4: File Generation
 
 1.  **Confirmation:** Announce you are finalizing the documents: "Excellent! I'm now creating and saving your product definition files."
 2.  **Write `product-definition.md`:**