|
| 1 | +<!-- Auto-synced from plugin. Do not edit manually. --> |
| 2 | + |
| 3 | +# .joggr/.gg/ |
| 4 | + |
| 5 | +A structured workflow system for managing development projects through a phased pipeline. |
| 6 | + |
| 7 | +## Workflow Pipeline |
| 8 | + |
| 9 | +``` |
| 10 | +/gg-new → /gg-discuss → /gg-research → /gg-plan → /gg-execute → /gg-verify |
| 11 | +``` |
| 12 | + |
| 13 | +Each step advances the workflow. `.joggr/.gg/state.json` tracks only the active project. Phase status is tracked in phase file YAML frontmatter. |
| 14 | + |
| 15 | +## Skills |
| 16 | + |
| 17 | +Skills are slash commands that drive the workflow. Each skill manages state transitions, user interaction, and agent orchestration. |
| 18 | + |
| 19 | +| Skill | Description | |
| 20 | +| ------------- | --------------------------------------------------------------------------------------------------------------- | |
| 21 | +| `gg-new` | Scaffold a project from a Linear issue/project or free-text description | |
| 22 | +| `gg-status` | Read-only tree view of project progress | |
| 23 | +| `gg-discuss` | Interview user to gather requirements (goals, constraints, preferences, edge cases, acceptance criteria) | |
| 24 | +| `gg-research` | Spawn background agent to explore codebase and web for technical context | |
| 25 | +| `gg-plan` | Create phase plan with tasks, file targets, acceptance criteria, and dependencies | |
| 26 | +| `gg-execute` | Group tasks into parallel waves and spawn executor agents | |
| 27 | +| `gg-verify` | Spawn verifier agent to check acceptance criteria with concrete evidence | |
| 28 | +| `gg-codebase` | Analyze repo and maintain `.joggr/.gg/codebase/` docs (stack, architecture, conventions, testing, integrations) | |
| 29 | +| `gg-help` | Display all available commands and usage | |
| 30 | + |
| 31 | +## Agents |
| 32 | + |
| 33 | +Agents are subagents spawned by skills to do the actual work. |
| 34 | + |
| 35 | +| Agent | Interactive? | Description | |
| 36 | +| --------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | |
| 37 | +| `researcher` | No (background) | Codebase + web researcher — explores code, maps dependencies, finds existing patterns | |
| 38 | +| `planner` | Yes | Task decomposer — breaks phases into tasks with file targets and acceptance criteria | |
| 39 | +| `executor` | No (background) | Task implementer — executes one task, validates with typecheck/lint/test | |
| 40 | +| `verifier` | No (background) | Acceptance verifier — checks every criterion with concrete evidence | |
| 41 | +| `codebase-researcher` | No (background) | Codebase analyst — explores repo with Serena MCP tools, writes focused docs to `.joggr/.gg/codebase/` | |
| 42 | + |
| 43 | +## Docs |
| 44 | + |
| 45 | +Internal documentation for agent authors. |
| 46 | + |
| 47 | +| File | Purpose | |
| 48 | +| ----------------------------- | --------------------------------------------------------------------- | |
| 49 | +| `docs/core/architecture.md` | Overview, definitions, component interaction diagram | |
| 50 | +| `docs/core/state.md` | State tracking, workflow artifacts, session persistence | |
| 51 | +| `docs/standards/interface.md` | How skills pass context to agents and how agents return results | |
| 52 | +| `docs/standards/agent.md` | Agent file structure, required/optional sections, example skeleton | |
| 53 | +| `docs/standards/skill.md` | Skill file structure, common patterns, example skeleton | |
| 54 | +| `docs/guides/linear.md` | Linear integration — ingestion, data flow, outcome vs. implementation | |
| 55 | +| `docs/core/principles.md` | Behavioral principles for building skills and agents | |
| 56 | + |
| 57 | +## Troubleshooting |
| 58 | + |
| 59 | +If GG is behaving unexpectedly, see `TROUBLESHOOTING.md` in this directory for common failure modes and recovery steps. |
| 60 | + |
| 61 | +## Templates |
| 62 | + |
| 63 | +Templates scaffolded by `gg-new` into `.joggr/.gg/projects/{project-slug}/`. |
| 64 | + |
| 65 | +| File | Purpose | |
| 66 | +| -------------------------- | ----------------------------------------------------- | |
| 67 | +| `input.md` | Raw requirements and user intent | |
| 68 | +| `discussion.md` | Timestamped interview log | |
| 69 | +| `research.md` | Technical research findings | |
| 70 | +| `overview.md` | Project overview and phase breakdown | |
| 71 | +| `plan.md` | Project-level plan with phase/task XML | |
| 72 | +| `phase.md` | Per-phase task plan with XML format | |
| 73 | +| `codebase/stack.md` | Technology stack reference template | |
| 74 | +| `codebase/architecture.md` | Architecture and structure reference template | |
| 75 | +| `codebase/conventions.md` | Code conventions and style reference template | |
| 76 | +| `codebase/testing.md` | Testing patterns and framework reference template | |
| 77 | +| `codebase/integrations.md` | External integrations and services reference template | |
| 78 | + |
| 79 | +## Runtime Directory |
| 80 | + |
| 81 | +When a project is active, the working directory looks like: |
| 82 | + |
| 83 | +``` |
| 84 | +.joggr/.gg/ |
| 85 | +├── state.json # Workflow state |
| 86 | +├── settings.json # GG configuration |
| 87 | +├── settings.local.json # Local overrides (gitignored) |
| 88 | +├── codebase/ # Shared codebase documentation |
| 89 | +│ ├── stack.md |
| 90 | +│ ├── architecture.md |
| 91 | +│ ├── conventions.md |
| 92 | +│ ├── testing.md |
| 93 | +│ └── integrations.md |
| 94 | +└── projects/ # All project directories |
| 95 | + └── {project-slug}/ # Per-project directory |
| 96 | + ├── input.md |
| 97 | + ├── discussion.md |
| 98 | + ├── research.md |
| 99 | + ├── overview.md |
| 100 | + ├── plan.md |
| 101 | + └── phases/ |
| 102 | + └── <N>-<slug>/ |
| 103 | + └── phase.md # Per-phase task plans |
| 104 | +``` |
0 commit comments