Add Tech Stack Documentation System

.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`
+

.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: <what this project does>
+
+## Core Stack
+
+### Application Framework & Runtime
+- App framework: <framework name and version>
+- Language: <primary language(s) with versions>
+- Runtime: <Node.js, Deno, Bun, Python, etc. with versions>
+- Package manager: <npm, yarn, pnpm, bun, pip, etc.>
+
+### Build & Development Tools
+- Monorepo tooling: <Turborepo, Nx, Lerna, or N/A>
+- Build tool: <Vite, Webpack, esbuild, etc.>
+- Module system: <ESM, CommonJS, etc.>
+
+### Frontend (if applicable)
+- UI framework: <React, Vue, Svelte, etc. with version>
+- CSS framework: <Tailwind, Bootstrap, styled-components, etc.>
+- UI component library: <Radix, MUI, Chakra, custom, etc.>
+- Icons: <lucide-react, heroicons, font-awesome, etc.>
+- Fonts: <Google Fonts, custom, system>
+
+### Backend (if applicable)
+- Server framework: <Express, Fastify, NestJS, Django, FastAPI, etc.>
+- API style: <REST, GraphQL, tRPC, gRPC>
+- Authentication: <Auth0, Clerk, Better Auth, custom JWT, etc.>
+
+### Data & State Management
+- Forms & validation: <library and schema validator>
+- State management: <Redux, Zustand, Jotai, Context, etc.>
+- Data fetching: <React Query, SWR, Apollo, native fetch>
+- Database: <PostgreSQL, MySQL, MongoDB, etc.>
+- ORM/Query builder: <Prisma, Drizzle, TypeORM, Sequelize, SQLAlchemy, etc.>
+
+### Testing & Quality
+- Testing framework: <Vitest, Jest, Playwright, Cypress, pytest, etc.>
+- Linting: <ESLint, Biome, Ruff, etc.>
+- Formatting: <Prettier, Biome, Black, etc.>
+- Type checking: <TypeScript, mypy, etc.>
+
+### Hosting & Infrastructure
+- Application hosting: <Vercel, Netlify, AWS, GCP, Heroku, etc.>
+- Database hosting: <Neon, Supabase, PlanetScale, RDS, etc.>
+- CDN: <Cloudflare, Vercel Edge, CloudFront, etc.>
+- Asset storage: <S3, Cloudinary, built-in>
+
+### CI/CD & DevOps
+- CI/CD platform: <GitHub Actions, GitLab CI, CircleCI, etc.>
+- Deployment trigger: <PR previews, branch deployments, manual>
+- Environments: <production, staging, preview, development>
+
+### AI & External Services (if applicable)
+- AI/LLM: <OpenAI, Anthropic, AI SDK, LangChain, etc.>
+- Analytics: <Google Analytics, Plausible, Mixpanel, etc.>
+- Monitoring: <Sentry, DataDog, LogRocket, etc.>
+- Email: <SendGrid, Resend, Postmark, etc.>
+
+## Product Capabilities
+
+Key features or workflows this stack enables:
+- <Capability 1>
+- <Capability 2>
+- <Capability 3>
+
+## Constraints & Requirements
+
+Technical or business constraints that shaped these choices:
+- <Constraint 1: e.g., must be serverless>
+- <Constraint 2: e.g., GDPR compliance required>
+- <Constraint 3: e.g., budget limitations>
+
+## Future Integrations (Roadmap)
+
+Planned additions or changes:
+- <Future tech 1>
+- <Future tech 2>
+
+## Decision Rationale (Optional)
+
+Why key technologies were chosen:
+- **<Technology>**: <reasoning for selection>
+- **<Technology>**: <reasoning for selection>
+
+---
+
+**Template Version**: 1.0  
+**Last Updated**: <date>
+

.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
+

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`.