Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.joggr.ai/llms.txt

Use this file to discover all available pages before exploring further.

Not every change needs a multi-phase project. A bug fix, a rename, a small feature toggle — these are well-scoped enough that the overhead of /gg-new with separate discuss, research, plan, execute, and verify invocations is unnecessary. /gg-task runs the entire pipeline in one session and produces two artifacts instead of a full project directory.

​
When to Use /gg-task vs /gg-new

/gg-task

Small, well-scoped changes. A bug fix, a rename, adding a config option. Single session, two artifacts (spec.md and plan.md), no separate phase files.

/gg-new

Multi-file features, cross-cutting refactors, work that spans multiple apps or packages. Full project scaffolding with separate phases, review gates between stages, and team coordination.
Use /gg-task when:
  • The change is small and well-scoped (a bug fix, a rename, adding a toggle)
  • You do not need multi-phase planning or team coordination
  • You want to go from idea to implementation without leaving the terminal
Use /gg-new when:
  • The change spans multiple apps or packages
  • You need multi-phase planning with separate review gates
  • Multiple developers will collaborate on the implementation

​
The Six-Step Workflow

/gg-task moves through six steps in order. Each step updates the step field in spec.md frontmatter, so the skill always knows where it left off.
1

New

Task scaffolding. The skill derives a slug from your description, creates .joggr/.gg/tasks/ {slug}/, and writes an initial spec.md with YAML frontmatter tracking workflow state.
2

Discuss

Structured interview to clarify goals, constraints, edge cases, and acceptance criteria. The skill asks targeted questions and iterates if answers are vague — a shallow discussion produces a weak plan. Answers are appended to the Discussion section of spec.md.
3

Research

Codebase analysis. The researcher agent identifies relevant files, existing patterns, and dependencies, then surfaces 2-3 implementation approaches. You pick the approach before anything is committed to the spec. After research, the review UI opens so you can edit the spec before planning.
4

Plan

Flat task list generation. The planner agent reads the approved spec and produces plan.md with a set of concrete tasks. The review UI opens again so you can approve or edit the plan before execution starts.
5

Execute

Parallel code implementation. Tasks are grouped into conflict-free waves and multiple executor agents run in parallel within each wave. Validation (typecheck, lint, tests) runs after each task. You checkpoint and confirm after each wave before continuing.
6

Verify

Acceptance criteria validation. The verifier agent checks each criterion from spec.md against the actual code changes and reports pass/fail per criterion. If criteria fail, you can fix and re-verify or accept as-is.

​
Starting a Task

Pass a description (rough idea is fine): 
/gg-task add retry logic to the webhook handler
The skill derives a slug (add-retry-logic), creates the task directory, and walks through all six steps. You can also pass just a slug if you prefer: 
/gg-task fix-pagination-bug

​
Artifact Structure

After a full run, the task directory contains two files:
spec.md is the evolving specification. YAML frontmatter tracks the current workflow step and status. The body accumulates discussion notes, research findings, and acceptance criteria as the workflow progresses. plan.md is the task list. It always uses a <phases> wrapper — one or more phases each containing a task list — in a single file, never separate phase directories.

​
Resume Behavior

If your session is cleared or times out mid-workflow, re-invoke with the same slug: 
/gg-task add-retry-logic
The skill reads spec.md frontmatter and picks up where you left off. Completed steps are skipped. Steps interrupted mid-run are retried from the beginning, except execution — which resumes from the last incomplete task. If only one task exists in .joggr/.gg/tasks/, the skill auto-resolves it — no slug needed: 
/gg-task

​
Examples

​
Bug Fix

/gg-task fix the off-by-one error in pagination
Produces a spec focused on the pagination logic, a plan with 2-3 tasks (fix the offset calculation, add a boundary check, verify edge cases), and executes the fix in one session.

​
Rename

/gg-task rename UserProfile component to AccountProfile
Research identifies all references across the codebase. The plan covers the component file, imports, and tests. Execution updates everything in one pass.

​
Small Feature

/gg-task add retry logic to the webhook handler
Discussion captures retry count, backoff strategy, and logging requirements. Research finds the existing retry utility. The plan integrates them. Execution wires it up and verifies acceptance criteria.