Skip to content

Refine agents #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
davidmiuraactualai wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Refine agents #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94329e7
Refine agents
davidmiuraactualai Apr 11, 2026
1c904fe
Update packs
davidmiuraactualai Apr 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 190 additions & 0 deletions packs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,190 @@
# Actual Software Factory — Gas City Agent Packs

A self-contained set of Gas City custom-agent packs implementing the
8 Agent Operations described at
[actual.ai/softwarefactory](https://www.actual.ai/softwarefactory):

1. **Architect** — set architectural rules; access controls, trust
boundaries, guardrails
2. **Plan / Work Breakdown** — create work packages from high-level
goals
3. **UI/UX Design** — wireframes, design systems, a11y audits
4. **Validate / Test Cases** — write failing tests from acceptance
criteria
5. **Build Code** — implement against the test suite
6. **Code Review** — automated review for style, security, spec
compliance
7. **Deploy / Release Gate** — quality gate with rollback plan
8. **Improve / Feedback Loop** — runtime signals back into the spec

Each operation is one pack. Each pack is a single custom Gas City
agent with its own prompt template, formula, order gate, doctor
check, and commands. The 9th pack (`all/`) is a thin composition
shell that `includes` all 8 leaf packs.

## Directory layout

```
examples/actual/
├── README.md # you are here
├── city.toml # runnable sample workspace
├── architect/ # Principal-Engineer persona
├── planner/ # Product-Manager + Program-Manager persona
│ # (ships the tracker-to-beads bridge skill)
├── designer/ # UI/UX-Designer + Accessibility-Engineer persona
├── validator/ # QA-Engineer persona
├── builder/ # Backend+Frontend generalist persona
├── reviewer/ # Engineering-Manager + Principal-Engineer +
│ # Security-Engineer persona
├── release-gate/ # Release-Engineer + DevOps-Engineer persona
├── improver/ # SRE + Performance-Engineer + DevRel persona
└── all/ # composition pack — includes all 8
```

## Persona mapping

The agent voices are anchored to the built-in personas from
[`actual-factory`](file:///Users/david_miura_actual_ai/Projects/actual-software/actual-factory/extensions/factory-vscode/shared/actual-agents/built-in-agents.ts):

| Pack | Anchor persona(s) |
|------|-------------------|
| architect | `principal-engineer` + `solutions-architect` |
| planner | `product-manager` + `program-manager` |
| designer | `ui-ux-designer` + `accessibility-engineer` |
| validator | `qa-engineer` |
| builder | `backend-engineer` + `frontend-engineer` |
| reviewer | `engineering-manager` + `principal-engineer` + `security-engineer` |
| release-gate | `release-engineer` + `devops-engineer` |
| improver | `sre` + `performance-engineer` + `developer-advocate` |

## The actual-skill integration

Three packs — **architect**, **planner**, **builder** — vendor the
upstream [actual-software/actual-skill](https://github.com/actual-software/actual-skill)
Claude Code companion for the `actual` CLI
(ADR-powered CLAUDE.md/AGENTS.md generator). The skill sits under
each pack's `overlays/default/.claude/skills/actual/` and is picked
up automatically when the agent starts.

To re-vendor after upstream releases a new version:

```bash
cd examples/actual/architect && ./scripts/sync-actual-skill.sh
cd examples/actual/planner && ./scripts/sync-actual-skill.sh
cd examples/actual/builder && ./scripts/sync-actual-skill.sh
```

The three packs use the skill slightly differently:

- **architect** runs `actual adr-bot --dry-run --full` to keep ADRs
and generated rules in sync
- **planner** reads `CLAUDE.md` / `AGENTS.md` for architectural
context when breaking down work
- **builder** runs `actual status` before coding to verify the rig
is not in ADR drift (and hands the work back to the architect if
it is)

## The tracker → beads bridge (planner only)

The planner pack also ships a second, pack-local skill:
`tracker-to-beads`. This skill probes `.claude/skills/` for any
sibling matching `jira`, `linear`, `github-issues`, or `tracker-*`
and calls its `list-issues` verb to materialize each external issue
as a bead. The mapping is recorded idempotently in
`.actual/planner/tracker-sync.json`.

**The builder downstream only ever reads beads** — tracker
credentials, API quirks, and rate limits are entirely the sibling
tracker skill's problem. The rest of the factory is tracker-agnostic.

If no tracker skill is installed, the step is a no-op and the
planner just breaks down whatever beads already exist. Users run
the factory in pure bd-first mode, hybrid mode, or tracker-first
mode without touching any config.

See [`planner/README.md`](planner/README.md) for the sibling-skill
contract (`scripts/list-issues.sh` printing a JSON array).

## Handoff protocol

There is **no master orchestrator**. Each pack's order gate matches
on a bead label; the flow is emergent from labels, not hardcoded:

```
needs-architecture needs-plan
(user) ────────────────────► architect ──────────► planner
▲ │
│ (drift hand-back) │
│ ▼
│ ┌──────────┬──────────┐
│ ▼ ▼ ▼
│ needs-design needs-tests ready-to-build
│ │ │ │
│ designer validator │
│ │ │ │
│ └──────────┴───────┘
│ │
│ ▼ ready-to-build
│ builder
│ │
│ ▼ needs-review
│ reviewer
│ ┌─────────┴─────────┐
│ ▼ ▼
│ ready-to-build ready-to-ship
│ (back to builder) │
│ ▼
│ release-gate
│ │
│ ▼ needs-improve
│ improver (24h cooldown)
│ │
└─────────────────────────────┘
(route upstream)
```

Rewire the flow by changing labels, not by editing Go or TOML. This
honors Gas City's core invariant: **ZERO hardcoded roles**.

## How to run

```bash
# 1. Register at least one rig (your project repo)
gc rig add /path/to/your/project

# 2. Start the factory — this brings up all 8 agents
gc start examples/actual/

# 3. File a goal to kick things off
bd create --title "Build user profiles" --label needs-architecture
```

The architect's order gate will match, wake the architect, which
runs `mol-architect-review`, produces rules and child beads labelled
`needs-plan`, which wakes the planner, and so on.

## Standalone use

Each leaf pack works on its own. To use just one:

```toml
# in your own city.toml
[workspace]
name = "mycity"
includes = ["/abs/path/to/examples/actual/builder"]
```

## Principles honored

- **ZERO hardcoded roles** — no Go is touched; role names live only
in pack.toml and prompt templates.
- **GUPP** — prompts include "If you find work on your hook, YOU
RUN IT" phrasing in the startup section.
- **ZFC** — formulas describe *structure* (step DAG), not judgment.
All decision-making lives in the markdown step descriptions.
- **NDI** — `wake_mode = "fresh"` + state-in-beads means every wake
re-derives state from durable storage.
- **No status files** — status.sh commands query `bd` live, never
read cached state files.
- **Label-based handoff** — the pipeline is emergent from order
gates + bead labels, never hardwired.
84 changes: 84 additions & 0 deletions packs/all/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# actual-factory (composition pack)

Brings up all 8 Agent Operations of the Actual Software Factory in
one include. Depends on the 8 sibling leaf packs under
`examples/actual/`.

## Usage

```toml
# city.toml at the top level of examples/actual/
[workspace]
name = "actual-factory"
provider = "claude"
includes = ["all"]
```

Or from outside this directory, with an absolute or relative path:

```toml
includes = ["/abs/path/to/gascity/examples/actual/all"]
```

## The 8 agents

| Operation | Pack | Label gate |
|-----------|------|------------|
| Architect | `../architect` | `needs-architecture` |
| Plan / Work Breakdown | `../planner` | `needs-plan` |
| UI/UX Design | `../designer` | `needs-design` |
| Validate / Test Cases | `../validator` | `needs-tests` |
| Build Code | `../builder` | `ready-to-build` |
| Code Review | `../reviewer` | `needs-review` |
| Deploy / Release Gate | `../release-gate` | `ready-to-ship` |
| Improve / Feedback Loop | `../improver` | cooldown (24h) |

## Handoff flow

```
(user or tracker issue)
│
▼ needs-architecture
architect ───────────► needs-plan ─► planner
▲ │
│ (hand-back) ▼
│ needs-design / needs-tests / ready-to-build
│ │
│ ┌───────────────┼───────────────┐
│ ▼ ▼ ▼
│ designer validator builder
│ │ │ │
│ └───► └───► │
│ ready-to-build ready-to-build │
│ ▼
│ needs-review
│ │
│ ▼
│ reviewer
│ ┌─────────┴─────────┐
│ ▼ ▼
│ ready-to-build ready-to-ship
│ (back to builder) │
│ ▼
│ release-gate
│ │
│ ▼
│ needs-improve
│ │
│ ▼
│ improver
│ │
└────────────────────────────────────────────────────────────────┘
(loop back to any upstream agent)
```

## Why this is a pack and not a master formula

The whole factory runs on **label-based handoff**. There is no master
orchestrator, no pipeline DAG hardcoded anywhere. Each pack's order
gate watches for its own label. Rewire the flow by changing labels,
not by editing Go or TOML.

This honors Gas City's core invariant: **ZERO hardcoded roles**.
Every leaf pack is self-describing. This composition pack just
bundles them for convenience.
26 changes: 26 additions & 0 deletions packs/all/pack.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# actual-factory — Composition pack that wires all 8 Agent Operations
# into a single runnable software factory.
#
# Includes every leaf pack in examples/actual/ via relative paths.
# Each leaf pack is also usable standalone — this one just bundles
# them so a user can bring the whole factory up with a single
# `includes = ["examples/actual/all"]` line in their city.toml.
#
# The "pipeline" is NOT hardcoded here. Each leaf pack's order gate
# matches on a bead label (needs-architecture, needs-plan, etc.)
# and wakes on its own. The flow is emergent from labels, not
# prescribed by Go or by this file.

[pack]
name = "actual-factory"
schema = 1
includes = [
"../architect",
"../planner",
"../designer",
"../validator",
"../builder",
"../reviewer",
"../release-gate",
"../improver",
]
93 changes: 93 additions & 0 deletions packs/architect/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# actual-architect

The **Architect** agent of the Actual Software Factory. One of eight
Agent-Operation packs under `examples/actual/`. Maps to the
"Architect" operation at https://www.actual.ai/softwarefactory.

## Persona

Principal Engineer + Solutions Architect. Prioritizes simplicity over
cleverness. Documents the *why* behind decisions. Thinks in trust
boundaries, access controls, guardrails, and end-to-end trade-offs.
Anchor personas are defined in
`actual-factory/extensions/factory-vscode/shared/actual-agents/built-in-agents.ts`.

## What it does

- Reads beads labelled `needs-architecture`
- Uses the bundled **actual** skill to run `actual adr-bot` and keep
`CLAUDE.md` / `AGENTS.md` in sync with the rig's ADRs
- Writes one-page guardrail rules under `.actual/rules/<topic>.md`
- Hands off to the **planner** by creating child beads with the
`needs-plan` label

## What it does NOT do

Write implementation code. Decompose work. Run CI. Review PRs.

## How to run

As part of the full factory:
```bash
gc rig add /path/to/your/project
gc start examples/actual/
```

Standalone (just this agent):
```bash
# add to a city.toml:
# [workspace]
# includes = ["examples/actual/architect"]
```

Manual dispatch of the formula against a specific bead:
```bash
gc sling <rig>/architect --on mol-architect-review \
--var topic=auth-boundaries
```

## Pack contents

| File | Purpose |
|------|---------|
| `pack.toml` | Agent + formulas + orders + doctor + commands declaration |
| `prompts/architect.md.tmpl` | The Principal-Engineer persona prompt |
| `formulas/mol-architect-review.formula.toml` | 5-step review workflow |
| `formulas/orders/architect-guardrail-check/order.toml` | Condition-gated auto-dispatch |
| `doctor/check-architect.sh` | Verifies `bd`, `gc`, `git`, `jq`, and (optional) `actual` |
| `commands/status.sh` | Shows architect work queue |
| `commands/rules.sh` | Lists rules under `.actual/rules/` |
| `scripts/sync-actual-skill.sh` | Author tool: re-vendor upstream actual-skill |
| `overlays/default/.claude/skills/actual/` | Vendored upstream actual-skill |

## Updating the vendored actual-skill

The `overlays/default/.claude/skills/actual/` tree is a verbatim copy
of `skills/actual/` from
[actual-software/actual-skill](https://github.com/actual-software/actual-skill).
When upstream publishes a new version:

```bash
./scripts/sync-actual-skill.sh # pulls main
./scripts/sync-actual-skill.sh v1.2.3 # pins to a tag
git diff -- overlays/default/.claude/skills/actual
```

Review and commit the diff.

## Handoff protocol

```
architect (this pack) → planner → designer/validator → builder
↓
reviewer
↓
release-gate
↓
improver
↓
(loop back)
```

Each step advances via a label change on the bead. No Go code, no
hardcoded pipeline — just beads and label-matching order gates.
Loading