Merge pull request #8 from lambda-curry/feature/core-workspace-split

Update TechStackAgent documentation to reflect new template location …

Author: jaruesink

.devagent/agents/TaskPlanner.md

@@ -0,0 +1,27 @@
+# Agent Roster
+
+Agents can be invoked when explicitly referenced with a leading hash (for example, `#ResearchAgent`) or when their agent file is mentioned (for example, `ResearchAgent.md`)
+
+## How to Think About Agents
+
+- Agents are structured prompt workflows that run inside this environment; they are not separate people to schedule meetings with.
+- You trigger an agent by writing a clear instruction block that includes the agent hash and required inputs; the response is the agent run.
+- The executing developer has standing approval to invoke any agent immediately; if a review is needed, capture it in a log after the run instead of delaying execution.
+- Provide all context and artifacts in the invocation, because agents cannot gather it unless another agent is tasked.
+- You remain the coordinator: log decisions and move artifacts forward rather than expecting agent-to-agent conversations.
+- Choose the lightest sequence that fits the work; simple enhancements can go straight to #ResearchAgent → #TaskExecutor, while complex features chain through #ProductMissionPartner → #FeatureClarifyAgent → #ResearchAgent → #SpecArchitect → #TaskPlanner → #TaskExecutor.
+- Choose the lightest sequence that fits the work; simple enhancements can go straight to #ResearchAgent → #TaskExecutor, while complex features chain through #ProductMissionPartner → #FeatureBrainstormAgent → #ResearchAgent → #SpecArchitect → #TaskPlanner → #TaskExecutor.
+- Workflows trigger manually—there is no background scheduler—so note any recurring reviews in change logs when you perform them.
+
+## Agents
+
+- #ProductMissionPartner — Co-creates the product mission and supporting assets. Utilize when product context or mission updates are needed. See `.devagent/core/agents/ProductMissionPartner.md`.
+- #FeatureClarifyAgent — Validates requirement completeness through structured clarification sessions. Utilize when feature ideas need validation before spec work, when specs have requirement gaps, or when requirements need completeness review. See `.devagent/core/agents/FeatureClarifyAgent.md`.
+- #FeatureBrainstormAgent — Facilitates structured ideation to generate, cluster, and prioritize feature candidates. Utilize when exploring solution spaces before research or when generating ideas from mission goals. See `.devagent/core/agents/FeatureBrainstormAgent.md`.
+- #ResearchAgent — Maps open questions and gathers vetted references. Utilize when a new feature needs discovery or spec clarification. See `.devagent/core/agents/ResearchAgent.md`.
+- #SpecArchitect — Synthesizes research into review-ready specs. Utilize when a spec draft or revision is required. See `.devagent/core/agents/SpecArchitect.md`.
+- #TaskPlanner — Breaks approved specs into sequenced, test-aware tasks. Utilize when planning implementation work. See `.devagent/core/agents/TaskPlanner.md`.
+- #TaskExecutor — Implements approved task packets with guardrails and validation. Utilize when tasks are ready for execution. See `.devagent/core/agents/TaskExecutor.md`.
+- #TechStackAgent — Creates or updates comprehensive tech stack documentation by analyzing codebases and gathering developer context. Utilize when documenting technology choices for a new or existing project. See `.devagent/core/agents/TechStackAgent.md`.
+- #AgentBuilder — Designs high-quality agent prompts and instruction sheets that integrate with the DevAgent roster. Utilize when creating new agents or updating agent templates. See `.devagent/core/agents/AgentBuilder.md`.
+- #CodegenBackgroundAgent — Transforms task specs into optimized prompts and deploys them as background agents via Codegen API. Utilize when tasks can be executed asynchronously with external AI agents. See `.devagent/core/agents/codegen/CodegenBackgroundAgent.md`.

.devagent/core/AGENTS.md

@@ -0,0 +1,210 @@
+# DevAgent Core Kit
+
+The DevAgent **core** kit is a portable collection of agent instruction sheets and reusable templates that enable structured product development workflows. Copy this entire `core/` directory to any project to gain immediate access to the full DevAgent roster and workflow templates.
+
+## What's Included
+
+- **Agent Instruction Sheets** (`agents/`) - Detailed briefs for 10+ specialized agents covering ideation, research, specification, planning, and execution
+- **Document Templates** (`templates/`) - Reusable structures for research packets, specs, task plans, and feature hubs
+- **Agent Roster** (`AGENTS.md`) - Quick reference guide for when to invoke each agent
+- **This Setup Guide** (`README.md`) - Instructions for initializing DevAgent in new projects
+
+## Core vs Workspace
+
+DevAgent separates **portable** artifacts (core) from **project-specific** artifacts (workspace):
+
+- **`.devagent/core/`** (this directory) - PORTABLE agent kit that can be copied to any project
+- **`.devagent/workspace/`** - PROJECT-SPECIFIC product mission, features, research, and decisions
+
+This separation enables **5-minute setup** for new projects: copy `core/`, create `workspace/` skeleton, customize your mission, and start working.
+
+## Directory Structure
+
+```
+.devagent/
+├── core/                              # PORTABLE - Copy to any project
+│   ├── agents/                        # Agent instruction sheets
+│   │   ├── ProductMissionPartner.md
+│   │   ├── FeatureClarifyAgent.md
+│   │   ├── FeatureBrainstormAgent.md
+│   │   ├── ResearchAgent.md
+│   │   ├── SpecArchitect.md
+│   │   ├── TaskPlanner.md
+│   │   ├── TaskExecutor.md
+│   │   ├── TechStackAgent.md
+│   │   ├── AgentBuilder.md
+│   │   └── codegen/
+│   │       └── CodegenBackgroundAgent.md
+│   ├── templates/                     # Reusable document templates
+│   │   ├── agent-brief-template.md
+│   │   ├── brainstorm-packet-template.md
+│   │   ├── clarification-packet-template.md
+│   │   ├── clarification-questions-framework.md
+│   │   ├── constitution-template.md
+│   │   ├── research-packet-template.md
+│   │   ├── spec-document-template.md
+│   │   ├── task-plan-template.md
+│   │   ├── task-prompt-template.md
+│   │   ├── tech-stack-template.md
+│   │   └── feature-hub-template/      # Template for new feature hubs
+│   │       ├── README.md
+│   │       ├── research/
+│   │       └── spec/
+│   ├── AGENTS.md                      # Agent roster documentation
+│   └── README.md                      # Core kit usage & setup instructions
+│
+└── workspace/                         # PROJECT-SPECIFIC - Changes per project
+    ├── product/                       # Product mission & strategy
+    │   ├── mission.md
+    │   ├── roadmap.md
+    │   └── guiding-questions.md
+    ├── memory/                        # Project constitution & decisions
+    │   ├── constitution.md
+    │   ├── decision-journal.md
+    │   ├── tech-stack.md
+    │   ├── overview.md
+    │   └── _archive/                  # Historical constitution snapshots
+    ├── features/                      # Feature hubs with research & specs
+    │   ├── README.md
+    │   └── YYYY-MM-DD_feature-slug/
+    │       ├── README.md
+    │       ├── research/
+    │       │   └── YYYY-MM-DD_topic.md
+    │       └── spec/
+    │           └── YYYY-MM-DD_spec.md
+    ├── research/                      # Cross-cutting research
+    │   └── YYYY-MM-DD_topic.md
+    └── tasks/                         # Task execution logs (future)
+        └── YYYY-MM-DD_task-id.md
+```
+
+## Quick Setup (< 5 Minutes)
+
+Initialize DevAgent in a new project with these steps:
+
+### 1. Copy the Core Kit
+```bash
+# From an existing DevAgent project
+cp -r .devagent/core /path/to/new-project/.devagent/
+
+# Or clone this repository and copy core/
+git clone <this-repo-url>
+cp -r devagent/.devagent/core /path/to/new-project/.devagent/
+```
+
+### 2. Create Workspace Skeleton
+```bash
+cd /path/to/new-project/.devagent
+mkdir -p workspace/{product,memory,features,research,tasks}
+mkdir -p workspace/memory/_archive
+```
+
+### 3. Initialize Product Mission
+```bash
+# Create your product mission document
+cat > workspace/product/mission.md << 'EOF'
+# Product Mission
+
+## Vision
+[What does success look like?]
+
+## Target Users
+[Who are we building for?]
+
+## Core Value Proposition
+[What unique value do we provide?]
+
+## Success Metrics
+[How will we measure impact?]
+EOF
+```
+
+### 4. Invoke Your First Agent
+Open your AI chat interface (Cursor, Codegen, etc.) and reference:
+```
+@.devagent/core/agents/ProductMissionPartner.md
+
+Help me refine our product mission based on:
+- Our target market is [X]
+- Our key differentiator is [Y]
+- Our success criteria are [Z]
+```
+
+### 5. Start Building
+- Use `#ResearchAgent` to explore new features
+- Use `#SpecArchitect` to document implementations
+- Use `#TaskPlanner` and `#TaskExecutor` to break down work
+- All artifacts save to `workspace/` while `core/` remains portable
+
+**Target Setup Time:** Under 5 minutes from copy to first agent invocation.
+
+## How Agents Use This Structure
+
+**Agents Read From:**
+- `core/agents/` - To understand their role and workflow
+- `core/templates/` - To structure their outputs consistently
+- `workspace/product/` - To align with product mission and strategy
+- `workspace/memory/` - To respect project constitution and decisions
+
+**Agents Write To:**
+- `workspace/features/YYYY-MM-DD_feature-slug/` - Research packets, specs
+- `workspace/memory/` - Constitution updates, decision journal entries
+- `workspace/research/` - Cross-cutting research that spans multiple features
+- `workspace/tasks/` - Task execution logs (future capability)
+
+**Key Principle:** `core/` provides the *how* (agent instructions + templates), while `workspace/` captures the *what* (your project's specific artifacts).
+
+## Usage Notes
+
+### Updating the Core Kit
+- When DevAgent core is updated, simply replace your `core/` directory with the new version
+- Your `workspace/` remains untouched during core updates
+- Review changelog below before updating to understand changes
+
+### Customizing for Your Team
+- **Recommended:** Keep `core/` unmodified for easy updates
+- **Team-specific customizations:** Add to `workspace/memory/constitution.md` instead
+- **Template extensions:** Reference core templates but save customized versions in your project docs
+
+### Cross-Project Learning
+- Share research and patterns by copying specific `workspace/` subdirectories between projects
+- The portable `core/` kit means setup is always < 5 minutes
+- Consider maintaining an internal "DevAgent template project" with your team's baseline `workspace/` structure
+
+## Agent Roster Quick Reference
+
+See `AGENTS.md` for full details. Common workflows:
+
+**Simple Enhancement:**
+1. `#ResearchAgent` - Explore the problem space
+2. `#TaskExecutor` - Implement directly from research
+
+**Complex Feature:**
+1. `#ProductMissionPartner` - Validate mission alignment
+2. `#FeatureBrainstormAgent` - Generate solution ideas
+3. `#ResearchAgent` - Gather technical context
+4. `#SpecArchitect` - Document the design
+5. `#TaskPlanner` - Break into tasks
+6. `#TaskExecutor` - Implement step by step
+
+**When Requirements Are Unclear:**
+- Insert `#FeatureClarifyAgent` after ideation to validate completeness
+- Use structured clarification sessions before committing to specs
+
+## Updates & Changelog
+
+### Version History
+- **2025-10-01** - Initial core-workspace split release
+  - Separated portable core from project-specific workspace
+  - Added comprehensive setup documentation
+  - Established < 5 minute setup target
+
+### Upcoming Features
+- Enhanced task execution logging in `workspace/tasks/`
+- Agent-to-agent handoff automation
+- Template versioning and migration tools
+
+---
+
+**Questions or Issues?** Review individual agent instructions in `agents/` or see the root `README.md` for project-specific context.
+

.devagent/core/README.md

@@ -16,14 +16,14 @@
 - Clarify usage patterns, optional approval gates, and escalation paths so teams can wire resources into their own environments without assuming extra roles.
 
 ## Knowledge Sources
-- Internal: `.devagent/agents/`, `.devagent/product/`, `.devagent/templates/`, `.devagent/README.md`.
+- Internal: `.devagent/core/agents/`, `.devagent/workspace/product/`, `.devagent/core/templates/`, `.devagent/README.md`.
 - External: Context7 library docs for tooling references, Exa search for industry examples when inputs are sparse.
 - Retrieval etiquette: Reuse existing patterns when agents share responsibilities; cite new research in `guiding-questions.md` if the source is tentative.
 
 ## Workflow
 1. Kickoff: Confirm mission statement and desired outputs.
 2. Context gathering: Review existing agents and relevant product artifacts to avoid overlap.
-3. Outline: Start from `.devagent/templates/agent-brief-template.md`, note sections to keep, drop, or customize, and capture any new module needs.
+3. Outline: Start from `.devagent/core/templates/agent-brief-template.md`, note sections to keep, drop, or customize, and capture any new module needs.
 4. Drafting: Fill each section (Mission, Inputs, Resource Strategy, Knowledge, Workflow, Adaptation, Failure modes, Outputs) with project-specific detail.
 5. Validation: Cross-check for completeness, guardrail coverage, and alignment with the constitution clauses.
 6. Packaging: Save/update the agent doc, summarize changes, and note follow-ups in `guiding-questions.md` if needed.
@@ -37,8 +37,8 @@
 - Surface conflicts with existing agents (duplicated mission or overlapping scope) and request direction before proceeding.
 
 ## Expected Output
-- Markdown agent brief saved under `.devagent/agents/<AgentName>.md` using the standard template or a documented variation.
-- Updates to shared templates when the base structure evolves, committed to `.devagent/templates/`.
+- Markdown agent brief saved under `.devagent/core/agents/<AgentName>.md` using the standard template or a documented variation.
+- Updates to shared templates when the base structure evolves, committed to `.devagent/core/templates/`.
 
 ## Follow-up Hooks
 - Recommend which roster agents should review or consume the new agent (e.g., #SpecArchitect, #TaskPlanner).