Skip to content

Commit 9672e7f

Browse files
codegen-sh[bot]jaruesink
codegen-sh[bot]
and
jaruesink
committed
Add tech stack documentation system
- Created tech-stack-template.md for reusable project documentation - Documented devagent's own tech stack in tech-stack.md - Created TechStackAgent for automated tech stack creation/updates - Registered TechStackAgent and AgentBuilder in AGENTS.md roster Co-authored-by: Jake Ruesink <jake@lambdacurry.dev>
1 parent 3310a52 commit 9672e7f

4 files changed

Lines changed: 340 additions & 0 deletions

File tree

‎.devagent/agents/TechStackAgent.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# TechStackAgent
2+
3+
## Mission
4+
- Primary goal: Create or update comprehensive tech stack documentation for any project by analyzing codebases and gathering context from developers.
5+
- Boundaries / non-goals: Does not install dependencies, configure build tools, or make architectural decisions; focuses solely on documenting existing or planned technology choices.
6+
- Success signals: Tech stack documentation is complete, accurate, follows the template structure, and provides clear rationale for technology choices.
7+
8+
## Inputs
9+
- Required:
10+
- Repository or project context (name, purpose, target domain)
11+
- Location for tech stack file (default: `.devagent/memory/tech-stack.md`)
12+
- Optional:
13+
- Existing package manifests (package.json, requirements.txt, pyproject.toml, Gemfile, go.mod)
14+
- Project documentation (README, architecture docs)
15+
- Developer preferences or constraints
16+
- Tech stack template customization needs
17+
- Request missing info by: Enumerate gaps with specific questions (e.g., "What database are you using?", "What's your primary UI framework?") and suggest common answers for the project type.
18+
19+
## Resource Strategy
20+
- Package manifest analysis (package.json, requirements.txt, etc.) - Parse to detect installed dependencies and versions
21+
- File system inspection (config files, directory structure) - Identify frameworks, build tools, and architectural patterns
22+
- `#ResearchAgent` (when technology choices need external validation) - Gather best practices and ecosystem context
23+
- Context7 library docs (when analyzing specific frameworks or tools) - Get authoritative documentation about detected technologies
24+
- Developer interview prompts (when automated detection is incomplete) - Ask structured questions to fill gaps
25+
- Escalation rules: If tech stack has conflicting signals (e.g., multiple frameworks), pause and request clarification before documenting
26+
27+
## Knowledge Sources
28+
- Internal:
29+
- `.devagent/memory/tech-stack-template.md` (canonical template structure)
30+
- `.devagent/memory/constitution.md` (tool-agnostic principles)
31+
- `.devagent/product/` (mission and constraints that inform tech choices)
32+
- External:
33+
- Repository package manifests and lock files
34+
- Build configuration files (vite.config, webpack.config, tsconfig.json, etc.)
35+
- CI/CD configuration (.github/workflows, .gitlab-ci.yml, etc.)
36+
- Context7 for framework documentation
37+
- Exa search for technology comparisons and decision rationale
38+
- Retrieval etiquette: Cache detection results to avoid repeated scans; cite sources for technology rationale
39+
40+
## Workflow
41+
1. **Kickoff / readiness checks**:
42+
- Confirm target repository or project
43+
- Verify tech stack file location (default: `.devagent/memory/tech-stack.md`)
44+
- Ask if creating new documentation or updating existing
45+
46+
2. **Context gathering**:
47+
- Scan for package manifests (package.json, requirements.txt, pyproject.toml, Gemfile, go.mod, composer.json)
48+
- Inspect build tool configs (vite.config, webpack.config, tsconfig.json, biome.json, .eslintrc, etc.)
49+
- Review CI/CD configs (.github/workflows/, vercel.json, netlify.toml, etc.)
50+
- Check database connections and ORM configs (prisma/, drizzle/, .env examples)
51+
- Read existing README and architecture docs
52+
- If existing tech-stack.md exists, load it for comparison
53+
54+
3. **Analysis and detection**:
55+
- Extract core stack (runtime, language, framework versions)
56+
- Identify build and development tools (monorepo, bundler, package manager)
57+
- Detect frontend stack (UI framework, CSS, component libraries, icons, fonts)
58+
- Identify backend stack (server framework, API style, authentication)
59+
- Map data layer (forms, state, fetching, database, ORM)
60+
- Find testing and quality tools (test framework, linting, formatting, type checking)
61+
- Document hosting and infrastructure (app hosting, database hosting, CDN, assets)
62+
- Note CI/CD and DevOps setup (platform, deployment triggers, environments)
63+
- Capture external services (AI, analytics, monitoring, email, etc.)
64+
65+
4. **Gap identification**:
66+
- Compare detected technologies against template sections
67+
- Generate specific questions for missing information
68+
- Suggest common answers based on project type and existing stack
69+
- Escalate ambiguities (e.g., "Found both Express and Fastify - which is primary?")
70+
71+
5. **Documentation drafting**:
72+
- Start from `.devagent/memory/tech-stack-template.md`
73+
- Fill detected sections with specific versions and tools
74+
- Add Product Capabilities based on feature set or mission
75+
- Document Constraints & Requirements from constitution or developer input
76+
- Include Future Integrations if roadmap exists
77+
- Add Decision Rationale for key technology choices (optional but recommended)
78+
79+
6. **Validation / QA**:
80+
- Cross-check versions against package manifests
81+
- Verify all template sections are addressed (or explicitly marked N/A)
82+
- Ensure consistency with tool-agnostic principles (if applicable)
83+
- Flag outdated dependencies or security concerns (informational only)
84+
85+
7. **Output packaging**:
86+
- Save to specified location (default: `.devagent/memory/tech-stack.md`)
87+
- Add metadata footer (version, last updated date)
88+
- Generate summary of changes if updating existing file
89+
90+
8. **Post-run logging**:
91+
- Log detection methods used and confidence levels
92+
- Note any unanswered questions or assumptions made
93+
- Recommend follow-up actions (e.g., "Consider documenting database migration strategy")
94+
95+
## Adaptation Notes
96+
- **For new projects**: Focus on planned stack, include decision rationale for each choice
97+
- **For existing projects**: Emphasize detected technologies, flag discrepancies between config and running code
98+
- **For monorepos**: Create tech-stack.md per workspace or consolidate with clear boundaries
99+
- **For tool-specific repos** (like devagent): Highlight tool-agnostic patterns and nested specializations
100+
- **For microservices**: Consider per-service tech stacks or unified platform documentation
101+
102+
## Failure & Escalation
103+
- Common blockers:
104+
- No package manifests found (pure infrastructure repos, scripts-only projects)
105+
- Conflicting signals (multiple frameworks, unclear primary database)
106+
- Incomplete configs (missing database connection details, no CI/CD setup)
107+
- Legacy or undocumented custom tooling
108+
- Recovery playbook:
109+
- For missing manifests: Inspect file extensions and imports to infer language/frameworks
110+
- For conflicts: List all detected options and request developer clarification
111+
- For incomplete configs: Mark sections as "To be determined" and generate specific questions
112+
- For custom tooling: Document as-is with notes for future research
113+
114+
## Expected Output
115+
- Artifacts:
116+
- `tech-stack.md` at specified location (default: `.devagent/memory/tech-stack.md`)
117+
- Summary of detected technologies and confidence levels
118+
- List of unanswered questions or gaps (if any)
119+
- Communication:
120+
- "Tech stack documented for [project name] with [X] detected technologies and [Y] manual inputs required."
121+
- Link to created/updated file
122+
- Highlight any critical gaps or recommendations
123+
124+
## Follow-up Hooks
125+
- Downstream agents:
126+
- `#ProductMissionPartner` relies on tech stack for mission alignment
127+
- `#SpecArchitect` references tech stack for feasibility checks
128+
- `#TaskPlanner` uses tech stack to identify testing and build requirements
129+
- `#ResearchAgent` may validate technology choices against best practices
130+
- Metrics / signals:
131+
- Track tech stack freshness (last updated date)
132+
- Monitor for dependency updates or security advisories
133+
- Log technology adoption patterns across projects
134+
135+
---
136+
137+
**Agent Version**: 1.0
138+
**Created**: 2025-10-01
139+
**Template Source**: `.devagent/templates/agent-brief-template.md`
140+

‎.devagent/memory/tech-stack-template.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Tech Stack Template
2+
3+
Use this template to document the technology stack for any project. Replace bracketed guidance with concrete details and remove sections that don't apply.
4+
5+
## Context
6+
7+
Brief project description and purpose: <what this project does>
8+
9+
## Core Stack
10+
11+
### Application Framework & Runtime
12+
- App framework: <framework name and version>
13+
- Language: <primary language(s) with versions>
14+
- Runtime: <Node.js, Deno, Bun, Python, etc. with versions>
15+
- Package manager: <npm, yarn, pnpm, bun, pip, etc.>
16+
17+
### Build & Development Tools
18+
- Monorepo tooling: <Turborepo, Nx, Lerna, or N/A>
19+
- Build tool: <Vite, Webpack, esbuild, etc.>
20+
- Module system: <ESM, CommonJS, etc.>
21+
22+
### Frontend (if applicable)
23+
- UI framework: <React, Vue, Svelte, etc. with version>
24+
- CSS framework: <Tailwind, Bootstrap, styled-components, etc.>
25+
- UI component library: <Radix, MUI, Chakra, custom, etc.>
26+
- Icons: <lucide-react, heroicons, font-awesome, etc.>
27+
- Fonts: <Google Fonts, custom, system>
28+
29+
### Backend (if applicable)
30+
- Server framework: <Express, Fastify, NestJS, Django, FastAPI, etc.>
31+
- API style: <REST, GraphQL, tRPC, gRPC>
32+
- Authentication: <Auth0, Clerk, Better Auth, custom JWT, etc.>
33+
34+
### Data & State Management
35+
- Forms & validation: <library and schema validator>
36+
- State management: <Redux, Zustand, Jotai, Context, etc.>
37+
- Data fetching: <React Query, SWR, Apollo, native fetch>
38+
- Database: <PostgreSQL, MySQL, MongoDB, etc.>
39+
- ORM/Query builder: <Prisma, Drizzle, TypeORM, Sequelize, SQLAlchemy, etc.>
40+
41+
### Testing & Quality
42+
- Testing framework: <Vitest, Jest, Playwright, Cypress, pytest, etc.>
43+
- Linting: <ESLint, Biome, Ruff, etc.>
44+
- Formatting: <Prettier, Biome, Black, etc.>
45+
- Type checking: <TypeScript, mypy, etc.>
46+
47+
### Hosting & Infrastructure
48+
- Application hosting: <Vercel, Netlify, AWS, GCP, Heroku, etc.>
49+
- Database hosting: <Neon, Supabase, PlanetScale, RDS, etc.>
50+
- CDN: <Cloudflare, Vercel Edge, CloudFront, etc.>
51+
- Asset storage: <S3, Cloudinary, built-in>
52+
53+
### CI/CD & DevOps
54+
- CI/CD platform: <GitHub Actions, GitLab CI, CircleCI, etc.>
55+
- Deployment trigger: <PR previews, branch deployments, manual>
56+
- Environments: <production, staging, preview, development>
57+
58+
### AI & External Services (if applicable)
59+
- AI/LLM: <OpenAI, Anthropic, AI SDK, LangChain, etc.>
60+
- Analytics: <Google Analytics, Plausible, Mixpanel, etc.>
61+
- Monitoring: <Sentry, DataDog, LogRocket, etc.>
62+
- Email: <SendGrid, Resend, Postmark, etc.>
63+
64+
## Product Capabilities
65+
66+
Key features or workflows this stack enables:
67+
- <Capability 1>
68+
- <Capability 2>
69+
- <Capability 3>
70+
71+
## Constraints & Requirements
72+
73+
Technical or business constraints that shaped these choices:
74+
- <Constraint 1: e.g., must be serverless>
75+
- <Constraint 2: e.g., GDPR compliance required>
76+
- <Constraint 3: e.g., budget limitations>
77+
78+
## Future Integrations (Roadmap)
79+
80+
Planned additions or changes:
81+
- <Future tech 1>
82+
- <Future tech 2>
83+
84+
## Decision Rationale (Optional)
85+
86+
Why key technologies were chosen:
87+
- **<Technology>**: <reasoning for selection>
88+
- **<Technology>**: <reasoning for selection>
89+
90+
---
91+
92+
**Template Version**: 1.0
93+
**Last Updated**: <date>
94+

‎.devagent/memory/tech-stack.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Tech Stack (DevAgent)
2+
3+
This documents the technology stack for the DevAgent repository. Refer to `.devagent/memory/tech-stack-template.md` for the canonical template structure.
4+
5+
## Context
6+
7+
DevAgent is a meta-development system that coordinates specialized AI agents for product planning, research, specification, and task execution. It's repository-based, tool-agnostic, and designed to work with any AI coding assistant (Cursor, Codegen, GitHub Copilot, etc.).
8+
9+
## Core Stack
10+
11+
### Application Framework & Runtime
12+
- Format: Markdown-based agent workflows
13+
- Language: Markdown for documentation, supports Python/TypeScript/any language for target projects
14+
- Runtime: Runs in any AI coding assistant environment (Cursor, Codegen, etc.)
15+
- Package manager: Tool-specific (target projects may use npm, pip, uv, etc.)
16+
17+
### Build & Development Tools
18+
- Monorepo tooling: N/A (single repository structure)
19+
- Build tool: N/A (documentation-driven)
20+
- Module system: File-based agent composition
21+
22+
### Agent Orchestration
23+
- Agent framework: Custom markdown-based agent briefs
24+
- Agent coordination: Manual trigger via hash references (e.g., `#ResearchAgent`, `#TaskExecutor`)
25+
- Agent roster: Defined in `AGENTS.md` and `.devagent/agents/` directory
26+
- Background execution: Codegen API via `#CodegenBackgroundAgent`
27+
28+
### Data & State Management
29+
- State storage: Git repository (commits, branches, PRs)
30+
- Memory system: `.devagent/memory/` (constitution, overview, decision journal)
31+
- Feature state: `.devagent/features/YYYY-MM-DD_feature-slug/` folders
32+
- Context persistence: Markdown files with ISO date prefixes
33+
34+
### Documentation & Templates
35+
- Agent briefs: Markdown following `.devagent/templates/agent-brief-template.md`
36+
- Feature templates: `.devagent/features/_template/`
37+
- Spec documents: `.devagent/templates/spec-document-template.md`
38+
- Task planning: `.devagent/templates/task-plan-template.md`
39+
40+
### Quality & Validation
41+
- Testing: Agent validation through execution and user feedback
42+
- Review process: Human-in-the-loop approval gates
43+
- Constitution enforcement: `.devagent/memory/constitution.md`
44+
- Decision tracking: `.devagent/memory/decision-journal.md`
45+
46+
### External Integrations
47+
- AI/LLM: Tool-agnostic (works with any AI coding assistant)
48+
- Background execution: Codegen API for async agent runs
49+
- CLI tools: `uv` for Python package management, `codegen` CLI for API access
50+
- Version control: Git and GitHub for all state and coordination
51+
52+
## Product Capabilities
53+
54+
DevAgent enables:
55+
- **Structured product planning** via `#ProductMissionPartner`
56+
- **Feature ideation** via `#FeatureBrainstormAgent`
57+
- **Requirement validation** via `#FeatureClarifyAgent`
58+
- **Research coordination** via `#ResearchAgent`
59+
- **Spec creation** via `#SpecArchitect`
60+
- **Task decomposition** via `#TaskPlanner`
61+
- **Implementation execution** via `#TaskExecutor`
62+
- **Background agent deployment** via `#CodegenBackgroundAgent`
63+
- **Agent creation** via `#AgentBuilder`
64+
65+
## Constraints & Requirements
66+
67+
Technical and design principles:
68+
- **Tool-agnostic**: Must work with any AI coding assistant (Cursor, Codegen, GitHub Copilot, etc.)
69+
- **Repository-based**: All state lives in Git, no external databases
70+
- **Markdown-first**: Human-readable, version-controlled documentation
71+
- **Date-prefixed artifacts**: ISO dates for chronological organization
72+
- **Manual triggers**: Explicit agent invocation via hash references
73+
- **Traceable hand-offs**: Clear input/output contracts between agents
74+
- **Constitution-aligned**: All agent actions respect `.devagent/memory/constitution.md`
75+
76+
## Future Integrations (Roadmap)
77+
78+
Planned additions:
79+
- **Multi-agent orchestration**: Parallel and sequential agent execution patterns
80+
- **Metrics dashboard**: Observability for agent performance and outcomes
81+
- **Template versioning**: Structured evolution of agent briefs and templates
82+
- **Cross-project memory**: Shared learnings across multiple codebases
83+
84+
## Architecture Decisions
85+
86+
Why key approaches were chosen:
87+
88+
- **Markdown-based agents**: Enables version control, human readability, and tool portability. Any AI assistant can read and execute agent briefs without custom tooling.
89+
90+
- **File-based state**: Git provides natural versioning, branching, and collaboration primitives. No separate database or service layer needed.
91+
92+
- **Hash-triggered invocation**: Explicit `#AgentName` syntax makes agent coordination transparent and searchable in conversation history.
93+
94+
- **Dated feature folders**: ISO date prefixes (`YYYY-MM-DD_feature-slug`) enable chronological browsing and automatic sorting without metadata.
95+
96+
- **Tool-agnostic design**: Nested tool-specific agents (`.devagent/agents/codegen/`) allow specialized integrations while keeping core workflows portable.
97+
98+
- **Constitution-first**: Central principles in `.devagent/memory/constitution.md` ensure consistent behavior across all agents and features.
99+
100+
---
101+
102+
**Tech Stack Version**: 1.0
103+
**Last Updated**: 2025-10-01
104+

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,6 @@ Agents can be invoked when explicitly referenced with a leading hash (for exampl
2222
- #SpecArchitect — Synthesizes research into review-ready specs. Utilize when a spec draft or revision is required. See `.devagent/agents/SpecArchitect.md`.
2323
- #TaskPlanner — Breaks approved specs into sequenced, test-aware tasks. Utilize when planning implementation work. See `.devagent/agents/TaskPlanner.md`.
2424
- #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`.
2527
- #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`.

0 commit comments

Comments
 (0)