# Phase 1.8: Add Workflows and Templated Artifacts - Context

**Gathered:** 2026-02-01
**Status:** Ready for planning

<domain>
## Phase Boundary

Create GSD-lite native workflows for codebase mapping and new project initialization. Convert OG GSD patterns to single-agent, grep-friendly format. Produce ARCHITECTURE.md and PROJECT.md templates optimized for GSD-lite's lightweight philosophy.

</domain>

<references>
## File References

**OG GSD Reference (read these for patterns, but adapt for single-agent):**
- `.claude/get-shit-done/templates/project.md` — PROJECT.md template with full structure
- `.claude/get-shit-done/templates/codebase/architecture.md` — Architecture template (we're merging multiple files into this)
- `.claude/get-shit-done/templates/codebase/stack.md` — Tech stack template (merge into ARCHITECTURE.md)
- `.claude/get-shit-done/templates/codebase/concerns.md` — Concerns template (DROP - log in WORK.md instead)
- `.claude/get-shit-done/workflows/map-codebase.md` — OG workflow (spawns parallel agents - adapt to single-agent)
- `.claude/get-shit-done/workflows/discovery-phase.md` — OG new-project workflow (adapt to single-agent)

**Eval Artifacts (quality examples produced using OG GSD patterns):**
- `.planning/phases/01.8-.../evals/PROJECT.md` — Example PROJECT.md output
- `.planning/phases/01.8-.../evals/ARCHITECTURE.md` — Example ARCHITECTURE.md output (~40 lines, good density)
- `.planning/phases/01.8-.../evals/WORK.md` — Example WORK.md showing how logs connect to project

**GSD-lite Target Locations (where new files go):**
- `src/gsd_lite/template/workflows/map-codebase.md` — New workflow file (CREATE)
- `src/gsd_lite/template/workflows/new-project.md` — New workflow file (CREATE)
- `src/gsd_lite/template/ARCHITECTURE.md` — Template for codebase output (CREATE)
- `src/gsd_lite/template/PROJECT.md` — Template for project output (CREATE)
- `src/gsd_lite/template/PROTOCOL.md` — Add router hints (UPDATE)

**Key Distinction:**
- OG GSD (`.claude/`) = Multi-agent, spawns subagents, full-featured
- GSD-lite (`src/gsd_lite/template/`) = Single-agent, grep-friendly, lightweight

</references>

<decisions>
## Implementation Decisions

### ARCHITECTURE.md Structure (Codebase Mapper Output)
- Single merged file (not 7 separate files like OG GSD)
- **Project Structure Overview**: Table mapping directories to semantic meaning, two levels deep (root + one level down)
- **Tech Stack**: Condensed — runtime, language, 2-5 critical dependencies only
- **Data Flow**: Mermaid diagram OR 3-5 step text description
- **Entry Points**: "Start reading here" pointers
- Drop: concerns.md, conventions.md, integrations.md, testing.md, structure.md (log concerns in WORK.md as `[DISCOVERY]` entries instead)

### PROJECT.md Structure (New Project Output)
- **What This Is**: 2-3 sentence description
- **Core Value**: The ONE thing that must work
- **Success Criteria**: Simple checkbox list of "project succeeds when..." (NOT Requirements lifecycle tracking)
- **Context**: Background info informing implementation
- **Constraints**: Hard limits with rationale
- Drop: Key Decisions table (decisions logged in WORK.md instead)
- Drop: Validated/Active/Out of Scope breakdown (too heavy for GSD-lite)

### Integration with Existing Workflows
- **Standalone utilities**: Not part of moodboard/whiteboard/execution core loop
- **Soft gates** (suggest, don't block):
  - map-codebase: Suggest if ARCHITECTURE.md missing AND codebase exists
  - new-project: Suggest if PROJECT.md missing AND user states vision
- **Invocation**: Both natural language ("map the codebase") and explicit reference work
- **Router hints**: Add to PROTOCOL.md so agent infers when to suggest each workflow

### Claude's Discretion
- Exact wording of router hints in PROTOCOL.md
- Whether to include example ARCHITECTURE.md in template file
- Mermaid vs text for data flow (context-dependent)

</decisions>

<specifics>
## Specific Ideas

- "Convert OG GSD workflows to GSD-lite native" — agent got confused by OG GSD components that don't exist in GSD-lite (spawning multiple agents, etc.)
- User's eval artifacts at `.planning/phases/01.8-.../evals/` show the quality improvement when using OG GSD workflows — goal is to capture that quality natively
- ARCHITECTURE.md should be generalized for any project type (web apps, CLI tools, dbt projects, Docker infra, monorepos) — not just Docker containers
- PROJECT.md's Success Criteria provides the "5000ft view" that connects WORK.md logs to overall intent
- "WORK.md describes detailed logs, but PROJECT.md shows how those logs connect together"

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 01.8-add-workflows-templated-artifact-for-codebase-mapper-and-new-project-inspired-from-gsd-upstream-workflows*
*Context gathered: 2026-02-01*
