workflow

Files (5)

• SKILL.md
• git-conventions.md · references/
• hierarchy.md · references/
• log-entry.py · scripts/
• issue.md · templates/

SKILL.md (first lines)

# Workflow

Orchestrate work from conversation to shipped deliverables using a structured
hierarchy: Initiative → Project → Milestone → Issue → PR.

## The hierarchy

| Level | What it is | Where it lives | GitHub mapping |
|-------|-----------|----------------|----------------|
| Initiative | The overarching goal | The repo itself | — |
| Project | Self-contained body of work | `.lgtm/shared/plans/p{N}-{slug}/PLAN.md` | GitHub milestone |
| Milestone | Checkpoint within a project | Section in PLAN.md or sub-plan | Encoded in issue ID prefix |
| Issue | Atomic unit of work | `.lgtm/shared/plans/{project}/issues/P{N}M{M}-{NNN}.md` | One PR (issue ID in title) |
| Commit | Documents WHY | Git history | — |

Full naming conventions and filesystem layout: `references/hierarchy.md`
GitHub mapping rationale: `references/hierarchy.md`

## The workflow

### Step 1: Plan

Create `.lgtm/shared/plans/p{N}-{slug}/PLAN.md`.

- Define milestones and their dependency DAG
- Map file ownership (zero overlap between concurrent issues)
- Create milestone sub-plans if scope warrants: `.lgtm/shared/plans/{project}/m{N}-{name}.md`

### Step 2: Break into issues

Use `templates/issue.md` for the format. Write one file per issue to
`.lgtm/shared/plans/{project}/issues/`.

Each issue has:
- Acceptance criteria and test cases
- Dependencies (`depends_on` field)
- Open questions (must be resolved before status → `ready`)

Use the `issue-writer` agent for bulk creation from a plan.

### Step 3: Create base branch

```bash
git checkout master && git pull
git checkout -b {project}-base
git push -u origin {project}-base
```

One base branch per project. All issue branches target it.

### Step 4: Create GitHub milestone

```bash
gh api repos/{owner}/{repo}/milestones --method POST -f title="{project name}"
```

One milestone per project. Every PR gets attached.

### Step 5: Dispatch issues

Build the DAG from `depends_on` fields in issue files.

- An issue is **ready** when all its dependencies have merged PRs
- All ready issues dispatch in parallel
- Issues with no dependencies start immediately
- A failed issue only blocks issues that explicitly depend on it
- Zero file overlap between any two concurrent issues

For parallel execution, create worktrees:

```bash
git worktree add .claude/worktrees/{issue-id} -b {project}-{issue-slug} {project}-base
```

For sequential execution:

```bash
git checkout {project}-base
git checkout -b {project}-{issue-slug}
```

### Step 6: Execute

Each agent reads only its issue file. Follows `.claude/rules/agent-protocol.md`.

### Step 7: Quality review

After each agent completes, before creating the PR:

1. Does it meet the acceptance criteria from the issue file?
2. Do test cases pass?
3. Does the commit message explain WHY?

| Decision | Action |
|----------|--------|
| PASS | Create PR, attach to milestone |
| FAIL (minor) | Fix directly |
| FAIL (major) | Redeploy agent with correction notes |
| Max 3 attempts | Escalate to user |

### Step 8: Create PR

Issue ID in PR title — this is the contract:

```bash
gh pr create \
  --base {project}-base \
  --head {project}-{issue-slug} \
  --title "P{N}M{M}-{NNN}: short description" \
  --body "..."

gh pr edit {pr-number} --milestone "{project name}"
```

Git conventions: `references/git-conventions.md`

### Step 9: Update status

After each PR merges:

From thesaifpasha/LGTM, MIT.

More from thesaifpasha/LGTM