Skip to content

Commit fb4bd2c

Browse files
codegen-sh[bot]jaruesink
codegen-sh[bot]
and
jaruesink
committed
docs: Update documentation for core-workspace split (Task 3)
- Update AGENTS.md: All 10 agent references now use .devagent/core/agents/ paths - Create core/README.md: Comprehensive setup guide with directory structure and 5-minute setup instructions - Create core/AGENTS.md: Portable copy of agent roster for kit completeness - Update root README.md: Add structure section explaining core vs workspace, update all path references - Update templates: All self-references now use workspace/ paths for outputs This completes the documentation layer for the core-workspace split, enabling teams to easily adopt DevAgent in new projects by copying the portable core/ kit. Co-authored-by: Jake Ruesink <jaruesink@gmail.com>
1 parent 9e158c8 commit fb4bd2c

10 files changed

Lines changed: 293 additions & 38 deletions

‎.devagent/core/AGENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Agent Roster
2+
3+
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`)
4+
5+
## How to Think About Agents
6+
7+
- Agents are structured prompt workflows that run inside this environment; they are not separate people to schedule meetings with.
8+
- You trigger an agent by writing a clear instruction block that includes the agent hash and required inputs; the response is the agent run.
9+
- 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.
10+
- Provide all context and artifacts in the invocation, because agents cannot gather it unless another agent is tasked.
11+
- You remain the coordinator: log decisions and move artifacts forward rather than expecting agent-to-agent conversations.
12+
- 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.
13+
- 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.
14+
- Workflows trigger manually—there is no background scheduler—so note any recurring reviews in change logs when you perform them.
15+
16+
## Agents
17+
18+
- #ProductMissionPartner — Co-creates the product mission and supporting assets. Utilize when product context or mission updates are needed. See `.devagent/core/agents/ProductMissionPartner.md`.
19+
- #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`.
20+
- #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`.
21+
- #ResearchAgent — Maps open questions and gathers vetted references. Utilize when a new feature needs discovery or spec clarification. See `.devagent/core/agents/ResearchAgent.md`.
22+
- #SpecArchitect — Synthesizes research into review-ready specs. Utilize when a spec draft or revision is required. See `.devagent/core/agents/SpecArchitect.md`.
23+
- #TaskPlanner — Breaks approved specs into sequenced, test-aware tasks. Utilize when planning implementation work. See `.devagent/core/agents/TaskPlanner.md`.
24+
- #TaskExecutor — Implements approved task packets with guardrails and validation. Utilize when tasks are ready for execution. See `.devagent/core/agents/TaskExecutor.md`.
25+
- #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`.
26+
- #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`.
27+
- #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/README.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# DevAgent Core Kit
2+
3+
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.
4+
5+
## What's Included
6+
7+
- **Agent Instruction Sheets** (`agents/`) - Detailed briefs for 10+ specialized agents covering ideation, research, specification, planning, and execution
8+
- **Document Templates** (`templates/`) - Reusable structures for research packets, specs, task plans, and feature hubs
9+
- **Agent Roster** (`AGENTS.md`) - Quick reference guide for when to invoke each agent
10+
- **This Setup Guide** (`README.md`) - Instructions for initializing DevAgent in new projects
11+
12+
## Core vs Workspace
13+
14+
DevAgent separates **portable** artifacts (core) from **project-specific** artifacts (workspace):
15+
16+
- **`.devagent/core/`** (this directory) - PORTABLE agent kit that can be copied to any project
17+
- **`.devagent/workspace/`** - PROJECT-SPECIFIC product mission, features, research, and decisions
18+
19+
This separation enables **5-minute setup** for new projects: copy `core/`, create `workspace/` skeleton, customize your mission, and start working.
20+
21+
## Directory Structure
22+
23+
```
24+
.devagent/
25+
├── core/ # PORTABLE - Copy to any project
26+
│ ├── agents/ # Agent instruction sheets
27+
│ │ ├── ProductMissionPartner.md
28+
│ │ ├── FeatureClarifyAgent.md
29+
│ │ ├── FeatureBrainstormAgent.md
30+
│ │ ├── ResearchAgent.md
31+
│ │ ├── SpecArchitect.md
32+
│ │ ├── TaskPlanner.md
33+
│ │ ├── TaskExecutor.md
34+
│ │ ├── TechStackAgent.md
35+
│ │ ├── AgentBuilder.md
36+
│ │ └── codegen/
37+
│ │ └── CodegenBackgroundAgent.md
38+
│ ├── templates/ # Reusable document templates
39+
│ │ ├── agent-brief-template.md
40+
│ │ ├── brainstorm-packet-template.md
41+
│ │ ├── clarification-packet-template.md
42+
│ │ ├── clarification-questions-framework.md
43+
│ │ ├── constitution-template.md
44+
│ │ ├── research-packet-template.md
45+
│ │ ├── spec-document-template.md
46+
│ │ ├── task-plan-template.md
47+
│ │ ├── task-prompt-template.md
48+
│ │ ├── tech-stack-template.md
49+
│ │ └── feature-hub-template/ # Template for new feature hubs
50+
│ │ ├── README.md
51+
│ │ ├── research/
52+
│ │ └── spec/
53+
│ ├── AGENTS.md # Agent roster documentation
54+
│ └── README.md # Core kit usage & setup instructions
55+
│
56+
└── workspace/ # PROJECT-SPECIFIC - Changes per project
57+
├── product/ # Product mission & strategy
58+
│ ├── mission.md
59+
│ ├── roadmap.md
60+
│ └── guiding-questions.md
61+
├── memory/ # Project constitution & decisions
62+
│ ├── constitution.md
63+
│ ├── decision-journal.md
64+
│ ├── tech-stack.md
65+
│ ├── overview.md
66+
│ └── _archive/ # Historical constitution snapshots
67+
├── features/ # Feature hubs with research & specs
68+
│ ├── README.md
69+
│ └── YYYY-MM-DD_feature-slug/
70+
│ ├── README.md
71+
│ ├── research/
72+
│ │ └── YYYY-MM-DD_topic.md
73+
│ └── spec/
74+
│ └── YYYY-MM-DD_spec.md
75+
├── research/ # Cross-cutting research
76+
│ └── YYYY-MM-DD_topic.md
77+
└── tasks/ # Task execution logs (future)
78+
└── YYYY-MM-DD_task-id.md
79+
```
80+
81+
## Quick Setup (< 5 Minutes)
82+
83+
Initialize DevAgent in a new project with these steps:
84+
85+
### 1. Copy the Core Kit
86+
```bash
87+
# From an existing DevAgent project
88+
cp -r .devagent/core /path/to/new-project/.devagent/
89+
90+
# Or clone this repository and copy core/
91+
git clone <this-repo-url>
92+
cp -r devagent/.devagent/core /path/to/new-project/.devagent/
93+
```
94+
95+
### 2. Create Workspace Skeleton
96+
```bash
97+
cd /path/to/new-project/.devagent
98+
mkdir -p workspace/{product,memory,features,research,tasks}
99+
mkdir -p workspace/memory/_archive
100+
```
101+
102+
### 3. Initialize Product Mission
103+
```bash
104+
# Create your product mission document
105+
cat > workspace/product/mission.md << 'EOF'
106+
# Product Mission
107+
108+
## Vision
109+
[What does success look like?]
110+
111+
## Target Users
112+
[Who are we building for?]
113+
114+
## Core Value Proposition
115+
[What unique value do we provide?]
116+
117+
## Success Metrics
118+
[How will we measure impact?]
119+
EOF
120+
```
121+
122+
### 4. Invoke Your First Agent
123+
Open your AI chat interface (Cursor, Codegen, etc.) and reference:
124+
```
125+
@.devagent/core/agents/ProductMissionPartner.md
126+
127+
Help me refine our product mission based on:
128+
- Our target market is [X]
129+
- Our key differentiator is [Y]
130+
- Our success criteria are [Z]
131+
```
132+
133+
### 5. Start Building
134+
- Use `#ResearchAgent` to explore new features
135+
- Use `#SpecArchitect` to document implementations
136+
- Use `#TaskPlanner` and `#TaskExecutor` to break down work
137+
- All artifacts save to `workspace/` while `core/` remains portable
138+
139+
**Target Setup Time:** Under 5 minutes from copy to first agent invocation.
140+
141+
## How Agents Use This Structure
142+
143+
**Agents Read From:**
144+
- `core/agents/` - To understand their role and workflow
145+
- `core/templates/` - To structure their outputs consistently
146+
- `workspace/product/` - To align with product mission and strategy
147+
- `workspace/memory/` - To respect project constitution and decisions
148+
149+
**Agents Write To:**
150+
- `workspace/features/YYYY-MM-DD_feature-slug/` - Research packets, specs
151+
- `workspace/memory/` - Constitution updates, decision journal entries
152+
- `workspace/research/` - Cross-cutting research that spans multiple features
153+
- `workspace/tasks/` - Task execution logs (future capability)
154+
155+
**Key Principle:** `core/` provides the *how* (agent instructions + templates), while `workspace/` captures the *what* (your project's specific artifacts).
156+
157+
## Usage Notes
158+
159+
### Updating the Core Kit
160+
- When DevAgent core is updated, simply replace your `core/` directory with the new version
161+
- Your `workspace/` remains untouched during core updates
162+
- Review changelog below before updating to understand changes
163+
164+
### Customizing for Your Team
165+
- **Recommended:** Keep `core/` unmodified for easy updates
166+
- **Team-specific customizations:** Add to `workspace/memory/constitution.md` instead
167+
- **Template extensions:** Reference core templates but save customized versions in your project docs
168+
169+
### Cross-Project Learning
170+
- Share research and patterns by copying specific `workspace/` subdirectories between projects
171+
- The portable `core/` kit means setup is always < 5 minutes
172+
- Consider maintaining an internal "DevAgent template project" with your team's baseline `workspace/` structure
173+
174+
## Agent Roster Quick Reference
175+
176+
See `AGENTS.md` for full details. Common workflows:
177+
178+
**Simple Enhancement:**
179+
1. `#ResearchAgent` - Explore the problem space
180+
2. `#TaskExecutor` - Implement directly from research
181+
182+
**Complex Feature:**
183+
1. `#ProductMissionPartner` - Validate mission alignment
184+
2. `#FeatureBrainstormAgent` - Generate solution ideas
185+
3. `#ResearchAgent` - Gather technical context
186+
4. `#SpecArchitect` - Document the design
187+
5. `#TaskPlanner` - Break into tasks
188+
6. `#TaskExecutor` - Implement step by step
189+
190+
**When Requirements Are Unclear:**
191+
- Insert `#FeatureClarifyAgent` after ideation to validate completeness
192+
- Use structured clarification sessions before committing to specs
193+
194+
## Updates & Changelog
195+
196+
### Version History
197+
- **2025-10-01** - Initial core-workspace split release
198+
- Separated portable core from project-specific workspace
199+
- Added comprehensive setup documentation
200+
- Established < 5 minute setup target
201+
202+
### Upcoming Features
203+
- Enhanced task execution logging in `workspace/tasks/`
204+
- Agent-to-agent handoff automation
205+
- Template versioning and migration tools
206+
207+
---
208+
209+
**Questions or Issues?** Review individual agent instructions in `agents/` or see the root `README.md` for project-specific context.
210+

‎.devagent/core/templates/brainstorm-packet-template.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
- Mode: [exploratory | targeted | expansion]
44
- Session Date: YYYY-MM-DD
55
- Participants: [Names or "Solo"]
6-
- Storage Path: `.devagent/product/brainstorms/YYYY-MM-DD_<topic>.md`
6+
- Storage Path: `.devagent/workspace/product/brainstorms/YYYY-MM-DD_<topic>.md`
77
- Related Artifacts: [Links to mission, specs, prior brainstorms, or feature hubs]
88

99
## Problem Statement
@@ -148,4 +148,3 @@ _Lower-priority or future ideas preserved for later consideration._
148148
- Adjust evaluation criteria to match your product's mission metrics
149149
- Customize ideation techniques based on team preferences
150150
- Link related artifacts (specs, prior brainstorms) for traceability
151-

‎.devagent/core/templates/clarification-packet-template.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
- Date: <YYYY-MM-DD>
66
- Mode: <Feature Clarification | Gap Filling | Requirements Review>
77
- Status: <In Progress | Complete | Pending Research>
8-
- Related Feature Hub: `.devagent/features/YYYY-MM-DD_feature-slug/`
8+
- Related Feature Hub: `.devagent/workspace/features/YYYY-MM-DD_feature-slug/`
99
- Notes: Update validation status per dimension as clarification progresses. Use checkboxes for completion tracking.
1010

1111
## Feature Overview

‎.devagent/core/templates/research-packet-template.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
- Mode: <Spec | Task>
44
- Requested By: <Name>
55
- Last Updated: <YYYY-MM-DD>
6-
- Related Spec: `.devagent/features/YYYY-MM-DD_feature-slug/spec/<file>.md` (remove if Mode = Task and spec not yet created)
7-
- Related Task Plan (Optional): `.devagent/features/YYYY-MM-DD_feature-slug/tasks/<task-id>/<plan-file>.md`
6+
- Related Spec: `.devagent/workspace/features/YYYY-MM-DD_feature-slug/spec/<file>.md` (remove if Mode = Task and spec not yet created)
7+
- Related Task Plan (Optional): `.devagent/workspace/features/YYYY-MM-DD_feature-slug/tasks/<task-id>/<plan-file>.md`
88
- Storage Path: <Paste final file path>
99
- Stakeholders: <Name (Role)>
1010
- Notes: Remove sections marked `(Optional)` if not relevant.

‎.devagent/core/templates/spec-document-template.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
- Owner: <SpecArchitect or DRI>
44
- Last Updated: <YYYY-MM-DD>
55
- Status: <Draft | In Review | Approved>
6-
- Related Feature Hub: `.devagent/features/YYYY-MM-DD_feature-slug/`
6+
- Related Feature Hub: `.devagent/workspace/features/YYYY-MM-DD_feature-slug/`
77
- Stakeholders: <Name (Role, Decision Role)>
88
- Notes: Remove sections marked `(Optional)` if they do not apply.
99

‎.devagent/core/templates/task-plan-template.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
- Owner: <TaskPlanner or DRI>
44
- Last Updated: <YYYY-MM-DD>
55
- Status: <Draft | In Review | Approved>
6-
- Related Spec: `.devagent/features/YYYY-MM-DD_feature-slug/spec/<spec-file>.md`
6+
- Related Spec: `.devagent/workspace/features/YYYY-MM-DD_feature-slug/spec/<spec-file>.md`
77
- Notes: Keep backlog slices to five tasks or fewer; duplicate backlog sections as needed.
8-
- File Location: `.devagent/features/YYYY-MM-DD_feature-slug/tasks/<YYYY-MM-DD>_<descriptor>.md`
8+
- File Location: `.devagent/workspace/features/YYYY-MM-DD_feature-slug/tasks/<YYYY-MM-DD>_<descriptor>.md`
99

1010
## Summary
1111
Brief synopsis of the spec goal, key constraints, and planning focus.
@@ -33,4 +33,4 @@ Brief synopsis of the spec goal, key constraints, and planning focus.
3333
// Note: If no subtasks are needed for this task, omit the "Subtasks" section entirely.
3434

3535
### Task <2>
36-
<Repeat structure>
36+
<Repeat structure>

‎.devagent/core/templates/task-prompt-template.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,6 @@ Status values: `planned`, `in_progress`, `blocked`, `ready_for_review`, `done`.
5757
- 2025-09-29T00:00Z — Initial breakdown.
5858

5959
## Research Links
60-
- `.devagent/features/<feature_slug>/research/<date>_<topic>.md`
60+
- `.devagent/workspace/features/<feature_slug>/research/<date>_<topic>.md`
6161
- Additional context files or dashboards referenced in prompts.
6262

‎AGENTS.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ Agents can be invoked when explicitly referenced with a leading hash (for exampl
1515

1616
## Agents
1717

18-
- #ProductMissionPartner — Co-creates the product mission and supporting assets. Utilize when product context or mission updates are needed. See `.devagent/agents/ProductMissionPartner.md`.
19-
- #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/agents/FeatureClarifyAgent.md`.
20-
- #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/agents/FeatureBrainstormAgent.md`.
21-
- #ResearchAgent — Maps open questions and gathers vetted references. Utilize when a new feature needs discovery or spec clarification. See `.devagent/agents/ResearchAgent.md`.
22-
- #SpecArchitect — Synthesizes research into review-ready specs. Utilize when a spec draft or revision is required. See `.devagent/agents/SpecArchitect.md`.
23-
- #TaskPlanner — Breaks approved specs into sequenced, test-aware tasks. Utilize when planning implementation work. See `.devagent/agents/TaskPlanner.md`.
24-
- #TaskExecutor — Implements approved task packets with guardrails and validation. Utilize when tasks are ready for execution. See `.devagent/agents/TaskExecutor.md`.
25-
- #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/agents/TechStackAgent.md`.
26-
- #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/agents/AgentBuilder.md`.
27-
- #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/agents/codegen/CodegenBackgroundAgent.md`.
18+
- #ProductMissionPartner — Co-creates the product mission and supporting assets. Utilize when product context or mission updates are needed. See `.devagent/core/agents/ProductMissionPartner.md`.
19+
- #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`.
20+
- #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`.
21+
- #ResearchAgent — Maps open questions and gathers vetted references. Utilize when a new feature needs discovery or spec clarification. See `.devagent/core/agents/ResearchAgent.md`.
22+
- #SpecArchitect — Synthesizes research into review-ready specs. Utilize when a spec draft or revision is required. See `.devagent/core/agents/SpecArchitect.md`.
23+
- #TaskPlanner — Breaks approved specs into sequenced, test-aware tasks. Utilize when planning implementation work. See `.devagent/core/agents/TaskPlanner.md`.
24+
- #TaskExecutor — Implements approved task packets with guardrails and validation. Utilize when tasks are ready for execution. See `.devagent/core/agents/TaskExecutor.md`.
25+
- #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`.
26+
- #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`.
27+
- #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`.

0 commit comments

Comments
 (0)