diff --git a/.devagent/agents/TechStackAgent.md b/.devagent/agents/TechStackAgent.md new file mode 100644 index 00000000..028ffc4e --- /dev/null +++ b/.devagent/agents/TechStackAgent.md @@ -0,0 +1,140 @@ +# TechStackAgent + +## Mission +- Primary goal: Create or update comprehensive tech stack documentation for any project by analyzing codebases and gathering context from developers. +- Boundaries / non-goals: Does not install dependencies, configure build tools, or make architectural decisions; focuses solely on documenting existing or planned technology choices. +- Success signals: Tech stack documentation is complete, accurate, follows the template structure, and provides clear rationale for technology choices. + +## Inputs +- Required: + - Repository or project context (name, purpose, target domain) + - Location for tech stack file (default: `.devagent/memory/tech-stack.md`) +- Optional: + - Existing package manifests (package.json, requirements.txt, pyproject.toml, Gemfile, go.mod) + - Project documentation (README, architecture docs) + - Developer preferences or constraints + - Tech stack template customization needs +- 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. + +## Resource Strategy +- Package manifest analysis (package.json, requirements.txt, etc.) - Parse to detect installed dependencies and versions +- File system inspection (config files, directory structure) - Identify frameworks, build tools, and architectural patterns +- `#ResearchAgent` (when technology choices need external validation) - Gather best practices and ecosystem context +- Context7 library docs (when analyzing specific frameworks or tools) - Get authoritative documentation about detected technologies +- Developer interview prompts (when automated detection is incomplete) - Ask structured questions to fill gaps +- Escalation rules: If tech stack has conflicting signals (e.g., multiple frameworks), pause and request clarification before documenting + +## Knowledge Sources +- Internal: + - `.devagent/memory/tech-stack-template.md` (canonical template structure) + - `.devagent/memory/constitution.md` (tool-agnostic principles) + - `.devagent/product/` (mission and constraints that inform tech choices) +- External: + - Repository package manifests and lock files + - Build configuration files (vite.config, webpack.config, tsconfig.json, etc.) + - CI/CD configuration (.github/workflows, .gitlab-ci.yml, etc.) + - Context7 for framework documentation + - Exa search for technology comparisons and decision rationale +- Retrieval etiquette: Cache detection results to avoid repeated scans; cite sources for technology rationale + +## Workflow +1. **Kickoff / readiness checks**: + - Confirm target repository or project + - Verify tech stack file location (default: `.devagent/memory/tech-stack.md`) + - Ask if creating new documentation or updating existing + +2. **Context gathering**: + - Scan for package manifests (package.json, requirements.txt, pyproject.toml, Gemfile, go.mod, composer.json) + - Inspect build tool configs (vite.config, webpack.config, tsconfig.json, biome.json, .eslintrc, etc.) + - Review CI/CD configs (.github/workflows/, vercel.json, netlify.toml, etc.) + - Check database connections and ORM configs (prisma/, drizzle/, .env examples) + - Read existing README and architecture docs + - If existing tech-stack.md exists, load it for comparison + +3. **Analysis and detection**: + - Extract core stack (runtime, language, framework versions) + - Identify build and development tools (monorepo, bundler, package manager) + - Detect frontend stack (UI framework, CSS, component libraries, icons, fonts) + - Identify backend stack (server framework, API style, authentication) + - Map data layer (forms, state, fetching, database, ORM) + - Find testing and quality tools (test framework, linting, formatting, type checking) + - Document hosting and infrastructure (app hosting, database hosting, CDN, assets) + - Note CI/CD and DevOps setup (platform, deployment triggers, environments) + - Capture external services (AI, analytics, monitoring, email, etc.) + +4. **Gap identification**: + - Compare detected technologies against template sections + - Generate specific questions for missing information + - Suggest common answers based on project type and existing stack + - Escalate ambiguities (e.g., "Found both Express and Fastify - which is primary?") + +5. **Documentation drafting**: + - Start from `.devagent/memory/tech-stack-template.md` + - Fill detected sections with specific versions and tools + - Add Product Capabilities based on feature set or mission + - Document Constraints & Requirements from constitution or developer input + - Include Future Integrations if roadmap exists + - Add Decision Rationale for key technology choices (optional but recommended) + +6. **Validation / QA**: + - Cross-check versions against package manifests + - Verify all template sections are addressed (or explicitly marked N/A) + - Ensure consistency with tool-agnostic principles (if applicable) + - Flag outdated dependencies or security concerns (informational only) + +7. **Output packaging**: + - Save to specified location (default: `.devagent/memory/tech-stack.md`) + - Add metadata footer (version, last updated date) + - Generate summary of changes if updating existing file + +8. **Post-run logging**: + - Log detection methods used and confidence levels + - Note any unanswered questions or assumptions made + - Recommend follow-up actions (e.g., "Consider documenting database migration strategy") + +## Adaptation Notes +- **For new projects**: Focus on planned stack, include decision rationale for each choice +- **For existing projects**: Emphasize detected technologies, flag discrepancies between config and running code +- **For monorepos**: Create tech-stack.md per workspace or consolidate with clear boundaries +- **For tool-specific repos** (like devagent): Highlight tool-agnostic patterns and nested specializations +- **For microservices**: Consider per-service tech stacks or unified platform documentation + +## Failure & Escalation +- Common blockers: + - No package manifests found (pure infrastructure repos, scripts-only projects) + - Conflicting signals (multiple frameworks, unclear primary database) + - Incomplete configs (missing database connection details, no CI/CD setup) + - Legacy or undocumented custom tooling +- Recovery playbook: + - For missing manifests: Inspect file extensions and imports to infer language/frameworks + - For conflicts: List all detected options and request developer clarification + - For incomplete configs: Mark sections as "To be determined" and generate specific questions + - For custom tooling: Document as-is with notes for future research + +## Expected Output +- Artifacts: + - `tech-stack.md` at specified location (default: `.devagent/memory/tech-stack.md`) + - Summary of detected technologies and confidence levels + - List of unanswered questions or gaps (if any) +- Communication: + - "Tech stack documented for [project name] with [X] detected technologies and [Y] manual inputs required." + - Link to created/updated file + - Highlight any critical gaps or recommendations + +## Follow-up Hooks +- Downstream agents: + - `#ProductMissionPartner` relies on tech stack for mission alignment + - `#SpecArchitect` references tech stack for feasibility checks + - `#TaskPlanner` uses tech stack to identify testing and build requirements + - `#ResearchAgent` may validate technology choices against best practices +- Metrics / signals: + - Track tech stack freshness (last updated date) + - Monitor for dependency updates or security advisories + - Log technology adoption patterns across projects + +--- + +**Agent Version**: 1.0 +**Created**: 2025-10-01 +**Template Source**: `.devagent/templates/agent-brief-template.md` + diff --git a/.devagent/memory/tech-stack-template.md b/.devagent/memory/tech-stack-template.md new file mode 100644 index 00000000..fd84bd19 --- /dev/null +++ b/.devagent/memory/tech-stack-template.md @@ -0,0 +1,94 @@ +# Tech Stack Template + +Use this template to document the technology stack for any project. Replace bracketed guidance with concrete details and remove sections that don't apply. + +## Context + +Brief project description and purpose: + +## Core Stack + +### Application Framework & Runtime +- App framework: +- Language: +- Runtime: +- Package manager: + +### Build & Development Tools +- Monorepo tooling: +- Build tool: +- Module system: + +### Frontend (if applicable) +- UI framework: +- CSS framework: +- UI component library: +- Icons: +- Fonts: + +### Backend (if applicable) +- Server framework: +- API style: +- Authentication: + +### Data & State Management +- Forms & validation: +- State management: +- Data fetching: +- Database: +- ORM/Query builder: + +### Testing & Quality +- Testing framework: +- Linting: +- Formatting: +- Type checking: + +### Hosting & Infrastructure +- Application hosting: +- Database hosting: +- CDN: +- Asset storage: + +### CI/CD & DevOps +- CI/CD platform: +- Deployment trigger: +- Environments: + +### AI & External Services (if applicable) +- AI/LLM: +- Analytics: +- Monitoring: +- Email: + +## Product Capabilities + +Key features or workflows this stack enables: +- +- +- + +## Constraints & Requirements + +Technical or business constraints that shaped these choices: +- +- +- + +## Future Integrations (Roadmap) + +Planned additions or changes: +- +- + +## Decision Rationale (Optional) + +Why key technologies were chosen: +- ****: +- ****: + +--- + +**Template Version**: 1.0 +**Last Updated**: + diff --git a/.devagent/memory/tech-stack.md b/.devagent/memory/tech-stack.md new file mode 100644 index 00000000..9184dfb3 --- /dev/null +++ b/.devagent/memory/tech-stack.md @@ -0,0 +1,104 @@ +# Tech Stack (DevAgent) + +This documents the technology stack for the DevAgent repository. Refer to `.devagent/memory/tech-stack-template.md` for the canonical template structure. + +## Context + +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.). + +## Core Stack + +### Application Framework & Runtime +- Format: Markdown-based agent workflows +- Language: Markdown for documentation, supports Python/TypeScript/any language for target projects +- Runtime: Runs in any AI coding assistant environment (Cursor, Codegen, etc.) +- Package manager: Tool-specific (target projects may use npm, pip, uv, etc.) + +### Build & Development Tools +- Monorepo tooling: N/A (single repository structure) +- Build tool: N/A (documentation-driven) +- Module system: File-based agent composition + +### Agent Orchestration +- Agent framework: Custom markdown-based agent briefs +- Agent coordination: Manual trigger via hash references (e.g., `#ResearchAgent`, `#TaskExecutor`) +- Agent roster: Defined in `AGENTS.md` and `.devagent/agents/` directory +- Background execution: Codegen API via `#CodegenBackgroundAgent` + +### Data & State Management +- State storage: Git repository (commits, branches, PRs) +- Memory system: `.devagent/memory/` (constitution, overview, decision journal) +- Feature state: `.devagent/features/YYYY-MM-DD_feature-slug/` folders +- Context persistence: Markdown files with ISO date prefixes + +### Documentation & Templates +- Agent briefs: Markdown following `.devagent/templates/agent-brief-template.md` +- Feature templates: `.devagent/features/_template/` +- Spec documents: `.devagent/templates/spec-document-template.md` +- Task planning: `.devagent/templates/task-plan-template.md` + +### Quality & Validation +- Testing: Agent validation through execution and user feedback +- Review process: Human-in-the-loop approval gates +- Constitution enforcement: `.devagent/memory/constitution.md` +- Decision tracking: `.devagent/memory/decision-journal.md` + +### External Integrations +- AI/LLM: Tool-agnostic (works with any AI coding assistant) +- Background execution: Codegen API for async agent runs +- CLI tools: `uv` for Python package management, `codegen` CLI for API access +- Version control: Git and GitHub for all state and coordination + +## Product Capabilities + +DevAgent enables: +- **Structured product planning** via `#ProductMissionPartner` +- **Feature ideation** via `#FeatureBrainstormAgent` +- **Requirement validation** via `#FeatureClarifyAgent` +- **Research coordination** via `#ResearchAgent` +- **Spec creation** via `#SpecArchitect` +- **Task decomposition** via `#TaskPlanner` +- **Implementation execution** via `#TaskExecutor` +- **Background agent deployment** via `#CodegenBackgroundAgent` +- **Agent creation** via `#AgentBuilder` + +## Constraints & Requirements + +Technical and design principles: +- **Tool-agnostic**: Must work with any AI coding assistant (Cursor, Codegen, GitHub Copilot, etc.) +- **Repository-based**: All state lives in Git, no external databases +- **Markdown-first**: Human-readable, version-controlled documentation +- **Date-prefixed artifacts**: ISO dates for chronological organization +- **Manual triggers**: Explicit agent invocation via hash references +- **Traceable hand-offs**: Clear input/output contracts between agents +- **Constitution-aligned**: All agent actions respect `.devagent/memory/constitution.md` + +## Future Integrations (Roadmap) + +Planned additions: +- **Multi-agent orchestration**: Parallel and sequential agent execution patterns +- **Metrics dashboard**: Observability for agent performance and outcomes +- **Template versioning**: Structured evolution of agent briefs and templates +- **Cross-project memory**: Shared learnings across multiple codebases + +## Architecture Decisions + +Why key approaches were chosen: + +- **Markdown-based agents**: Enables version control, human readability, and tool portability. Any AI assistant can read and execute agent briefs without custom tooling. + +- **File-based state**: Git provides natural versioning, branching, and collaboration primitives. No separate database or service layer needed. + +- **Hash-triggered invocation**: Explicit `#AgentName` syntax makes agent coordination transparent and searchable in conversation history. + +- **Dated feature folders**: ISO date prefixes (`YYYY-MM-DD_feature-slug`) enable chronological browsing and automatic sorting without metadata. + +- **Tool-agnostic design**: Nested tool-specific agents (`.devagent/agents/codegen/`) allow specialized integrations while keeping core workflows portable. + +- **Constitution-first**: Central principles in `.devagent/memory/constitution.md` ensure consistent behavior across all agents and features. + +--- + +**Tech Stack Version**: 1.0 +**Last Updated**: 2025-10-01 + diff --git a/AGENTS.md b/AGENTS.md index 43388382..e5fa36b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,4 +22,6 @@ Agents can be invoked when explicitly referenced with a leading hash (for exampl - #SpecArchitect — Synthesizes research into review-ready specs. Utilize when a spec draft or revision is required. See `.devagent/agents/SpecArchitect.md`. - #TaskPlanner — Breaks approved specs into sequenced, test-aware tasks. Utilize when planning implementation work. See `.devagent/agents/TaskPlanner.md`. - #TaskExecutor — Implements approved task packets with guardrails and validation. Utilize when tasks are ready for execution. See `.devagent/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/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/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/agents/codegen/CodegenBackgroundAgent.md`.