Parker

Posted on Apr 8 • Edited on Apr 10

Agentic Development with Hizal

#ai #automation #agents #architecture

The goal: Rapidly ship production-ready software almost autonomously using Hizal's context engine, memory hierarchy, tools, skills, and governance capabilities for agent orchestration.

Principles:

"We are engineering back-pressure on the generative function." - Geoffrey Huntley
Hizal is the single source of truth. No external state tracking.
Subagents are stateless. They read from Hizal, work, write to Hizal, exit.
Every step produces an artifact. No step is skipped.
The spec chunk is the work item. Its status field IS the state machine.

Architecture Overview

Human ←→ Assistant Agent ←→ Orchestrator Agent
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
               Researcher      Planner          Coder
                Subagent       Subagent         Subagent
                    │               │               │
                    │               │               │
                    └───────┬───────┘               │
                            │                       │
                       QA Subagent          Delivery Subagent
                                                    │
                                              Operations Agent

Players:

| Agent | Persistence | Count | Runs on |
|-------|-------------|-------|---------|
| Assistant | Persistent | 1 per org | Mac Mini / always-on machine (OpenClaw) |
| Orchestrator | Persistent (heartbeat-driven) | 1 per project | Dedicated EC2 per project |
| Researcher | Ephemeral (subagent) | Spawned per work item | Same EC2 as Orchestrator |
| Planner | Ephemeral (subagent) | Spawned per work item | Same EC2 as Orchestrator |
| Coder | Ephemeral (subagent) | Spawned per work item | Same EC2 as Orchestrator |
| QA | Ephemeral (subagent) | Spawned per work item | Same EC2 as Orchestrator |
| Delivery | Ephemeral (subagent) | Spawned per packaging cycle | Same EC2 as Orchestrator |
| Operations | Persistent | 1 per org (or per project) | TBD |

Note: As you scale to more projects, agent type specialization lets you inject context more selectively. More agent types + more session lifecycle types = more precise injection.

Work Item Lifecycle

Every work item is a dev_spec chunk with a status custom field that tracks its progression. Subagents advance the status and create linked artifact chunks at each stage. The Orchestrator queries specs by status to decide what to do next.

Status State Machine

new → researched → planned → implemented → verified → packaged → deployed
                                                          ↑
                                              (human merges release PR)

Any status can transition to → blocked
blocked → (reverts to previous_status on resolution)

Status Definitions

Status	Set by	Means	Artifact Created
`new`	Assistant or Researcher	Spec exists, no work started	`dev_spec` chunk
`researched`	Researcher	Code analyzed, gaps identified	`dev_research` chunk linked to spec
`planned`	Planner	Implementation plan ready	`dev_plan` chunk linked to spec
`implemented`	Coder	Code written, PR open	`dev_implementation` chunk linked to spec
`verified`	QA	Tests pass, criteria met	`dev_verification` chunk linked to spec
`packaged`	Delivery	Merged into release branch PR	`dev_package` chunk linked to spec
`deployed`	Delivery	CI/CD completed	`dev_deployment` chunk linked to spec
`blocked`	Any agent	Cannot proceed	`blocked_reason` + `previous_status` fields set on spec
`rejected`	QA or Delivery	Rework needed	`dev_rejection` chunk linked to spec; status reverts to stage before the rejecting agent

Custom Fields on `dev_spec`

Field	Type	Required	Default	Purpose
`status`	enum	yes	`new`	Current workflow state
`priority`	enum	yes	`medium`	`critical`, `high`, `medium`, `low`
`blocked_reason`	text	no	—	Why this item is blocked
`previous_status`	enum	no	—	Status before `blocked` (for revert)
`ticket_url`	url	no	—	Link to external PM tool ticket (if applicable)

Requires: HIZAL-171 — Custom fields on chunk types

Blocked / Unblocked Flow

Any subagent sets spec status to blocked, writes previous_status = current status, writes blocked_reason
Orchestrator picks up blocked specs on next heartbeat (via list_chunks)
If Orchestrator can resolve: respawns the appropriate subagent, clears the block
If human input needed: updates spec's inject_audience to surface it to the Assistant
On resolution: status reverts to previous_status, previous_status and blocked_reason are cleared

Rejection Flow

QA creates dev_rejection chunk linked to spec with reason
QA reverts spec status to planned (sends it back to the Coder) or researched (sends it back to the Planner)
Orchestrator picks up the spec at its reverted status on next heartbeat
Orchestrator respawns the appropriate subagent with the rejection chunk as context

Orchestrator Queries

The Orchestrator's decision loop is now simple structured queries — no negative joins, no relationship inference:

# What needs attention?
list_chunks(chunk_type="dev_spec", custom_fields={"status": "blocked"})

# What's ready for each stage?
list_chunks(chunk_type="dev_spec", custom_fields={"status": "verified"}, sort="priority")    → package
list_chunks(chunk_type="dev_spec", custom_fields={"status": "implemented"}, sort="priority") → verify
list_chunks(chunk_type="dev_spec", custom_fields={"status": "planned"}, sort="priority")     → implement
list_chunks(chunk_type="dev_spec", custom_fields={"status": "researched"}, sort="priority")  → plan
list_chunks(chunk_type="dev_spec", custom_fields={"status": "new"}, sort="priority")         → research

The Assistant Agent

Purpose: Interface between humans and the agent team. Sounding board, spec drafter, notification layer.
Hizal Setup: dev_assistant agent type, dev_assisting session lifecycle. Injected with: agent identity, latest memory (via latest-N rule), blocked specs, pending packages.
Platform: OpenClaw on a persistent machine (Mac Mini).
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Role and Responsibilities

One Assistant per Organization. Has access to all projects but never writes code. This agent:

Drafts dev_spec chunks from conversations with the human (sets status to new, priority, and acceptance criteria)
Creates and maintains org-level Hizal content: principles, knowledge, conventions, constraints, decisions
Surfaces blocked specs to the human with context and resolves them on human's behalf
Notifies the human when release PRs (packages) are ready for review
Constantly creates memory chunks — should never truly forget anything
Learns the goals of the user/org over time and proactively enriches context

Session Lifecycle

Each conversation session:

Starts a dev_assisting Hizal session. Injected: latest memory chunk (via latest: N rule), any blocked specs surfaced by Orchestrator, any pending packages.
Engages with human — drafts specs, answers questions, resolves blockers.
On natural conversation break (topic change, long pause, explicit "that's all"): ends session, triggering consolidation.
Next session starts fresh with latest memory + any new injected chunks.

The session lifecycle is the memory boundary. No unbounded context growth.

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, chunk management, spec creation |
| Channels (Telegram) | Communication with human |
| Cron | Routine tasks (inbox checks, calendar, etc.) |
| Project Management (Forge MCP) | Syncing with external PM tools (optional) |
| Email/Calendar (gog-cli) | Notifications, scheduling |
| Web search + browser | Light research, verification |

The Orchestrator Agent

Purpose: Drive development on a single project. The project manager that never sleeps.
Hizal Setup: dev_orchestrator agent type, dev_orchestration session lifecycle. Injected with: agent identity, latest memory (via latest-N rule), org principles, project conventions and constraints.
Platform: OpenClaw on a dedicated EC2 per project. Heartbeat-driven.
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Role and Responsibilities

One Orchestrator per Project. On each heartbeat, the Orchestrator queries spec statuses and advances work items by spawning specialized subagents.

Orchestration Sequence

Each heartbeat:

Start session. Opens a dev_orchestration Hizal session. Latest memory and conventions auto-inject.
Query spec statuses. Use list_chunks to get all specs by status. This replaces complex relationship inference — one query per status level.
Triage blocked specs. Query status = blocked. For each: assess if the block can be resolved by respawning a subagent, or if human input is needed (escalate by updating spec's inject_audience to target the Assistant).
Advance work — work backwards from delivery:
- status = verified → spawn Delivery Subagent to package
- status = implemented → spawn QA Subagent to verify
- status = planned → spawn Coder Subagent to implement
- status = researched → spawn Planner Subagent to plan
- status = new → spawn Researcher Subagent to research

Within each status, pick the highest-priority spec first.

Save memory. Write a memory chunk summarizing what was accomplished and learned. The latest: N injection rule ensures only this memory auto-injects next session — no manual un-injection needed.
End session.

Parallelism: Step 4 can spawn multiple subagents concurrently across different specs. The Orchestrator doesn't wait for them to finish — it spawns and exits. Subagent output (status updates + artifact chunks) appears on the next heartbeat. Heartbeat interval controls development velocity.

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, spec status queries, orchestration |
| Project Management (Forge MCP) | Syncing ticket status (optional) |
| git/source-control | Viewing code, PRs, history |
| OpenCode | Spawning subagents |

Subagent Infrastructure

Subagents run as OpenCode sessions, spawned via the adh-spawn.sh wrapper script. This section documents the shared infrastructure that makes subagent execution consistent and reproducible.

Directory Structure

~/.adh/
├── agents/           # Per-agent AGENTS.md files (symlinked at spawn time)
│   ├── RESEARCHER.md
│   ├── PLANNER.md
│   ├── CODER.md
│   ├── QA.md
│   └── DELIVERY.md
├── configs/          # Per-agent OpenCode config files
│   ├── researcher.json
│   ├── planner.json
│   ├── coder.json
│   ├── qa.json
│   └── delivery.json
├── skills/          # Shared skills available to all agents
│   └── search-hizal/SKILL.md
├── keys/            # Per-agent Hizal API keys
│   ├── researcher
│   ├── planner
│   ├── coder
│   ├── qa
│   └── delivery
├── workspaces/      # Git worktrees (created at spawn time)
└── logs/           # Subagent invocation logs

Wrapper Script: `adh-spawn.sh`

The adh-spawn.sh script orchestrates subagent spawning:

adh-spawn.sh <agent_type> <ticket_id> [repo] [prompt]

What it does:

Resolves the Hizal API key for the agent type (~/.adh/keys/{type})
Sets up a git worktree (single-repo agents) or shared workspace (cross-repo agents)
Symlinks the correct AGENTS.md into the work directory
Exports OPENCODE_CONFIG pointing to the per-agent scoped config
Runs opencode run "<prompt>" with the work directory as cwd
Logs output to ~/.adh/logs/

Workspace modes:

Single-repo worktree (Coder): Creates a bare clone, then a worktree per ticket. Branch named feat/{ticket}-{agent}-work.
Shared workspace (Researcher, Planner, QA, Delivery): Clones both hizal/ and hizal-ui/ side-by-side. Used when an agent needs to work across both repos.

Scoped OpenCode Configs

Each agent type has its own OpenCode config at ~/.adh/configs/{type}.json. The adh-spawn.sh script exports OPENCODE_CONFIG to point to the correct file.

Key configuration per agent:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/minimax-m2.5-free",
  "mcp": {
    "hizal": {
      "type": "remote",
      "url": "https://hizal-api.xferops.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${HIZAL_API_KEY}"
      }
    }
  },
  "tools": {
    "write": <agent-specific>,
    "bash": <agent-specific>
  }
}

Tool permissions by agent:

Agent	`write`	`bash`	Rationale
Researcher	`false`	`true`	Read-only exploration
Planner	`true`	`false`	Writes PLAN chunks, no execution
Coder	`true`	`true`	Full code access
QA	`false`	`true`	Runs tests, no code changes
Delivery	`false`	`true`	Runs curl/gh checks only

Skills

Skills live at ~/.adh/skills/ and are symlinked into each work directory at spawn time. Currently:

search-hizal — How to search Hizal effectively. Covers semantic search, scopes, multi-pass strategy, exhaustive search checklist.

Hizal API Keys

Each agent type has its own Hizal API key, stored at ~/.adh/keys/{agent_type}. Keys are created in the Hizal UI under each agent's profile. This gives:

Per-agent key scoping (revoke one without affecting others)
Audit trail of which agent wrote what
Different permission levels per agent type if needed

The Researcher Subagent

Purpose: The R in RPI. Views specs through the lenses of existing code → relevant 3rd party docs → best practices. Produces quality research.
Hizal Setup: dev_researcher agent type, dev_research session lifecycle. Injected with: identity, org principles, project conventions and constraints.
Platform: Terminal coding agent (OpenCode) on the Orchestrator's EC2, in a git worktree.
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Sequence

Start session. Opens a dev_research Hizal session.
Read spec. Fetch the dev_spec chunk by query key. If the spec was created from an external PM tool, enrich it with codebase context and update the chunk.
Check memories. Search Hizal for memories of similar past work.
Search project context. Check for relevant project chunks. Always done before reading code.
Read the code. Explore the codebase. If project chunks from step 4 are inaccurate, update them via update_context.
External research (optional). Search for relevant blog posts, articles, research (web search, arXiv, docs).
Output. Either:
- Set spec status to blocked, write blocked_reason — if something prevents progress
- OR create a dev_research chunk — outlines what exists and what needs to change. No implementation specifics. Link to spec with reason. Update spec status to researched.
Save memories. Write memory chunks.

Tools

Tool	Purpose
Hizal MCP	Memory, context, chunk management, status updates
git/source-control	Reading current code, PRs, history
Web search	Docs, articles, research

The Planner Subagent

Purpose: The P in RPI. Reads the research and creates a phased implementation plan.
Hizal Setup: dev_planner agent type, dev_planning session lifecycle. Injected with: identity, org principles, project conventions and constraints.
Platform: Terminal coding agent (OpenCode) on the Orchestrator's EC2, in a git worktree.
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Sequence

Start session. Opens a dev_planning Hizal session.
Read the chain. Fetch the dev_spec chunk and its linked dev_research chunk by query keys.
Check memories. Search for memories of similar past work.
Search project context. Check for relevant project chunks. Always before code.
Read the code. Verify project chunks are accurate, update if needed.
Check 3rd party docs (if needed). Read up-to-date documentation (Context7 MCP, web search).
Output. Either:
- Set spec status to blocked, write blocked_reason
- OR create a dev_plan chunk with phased implementation steps, acceptance criteria per phase, and expected test coverage. Link to spec and research chunks with reasons. Update spec status to planned.
Save memories. Write memory chunks.

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, chunk management, status updates |
| git/source-control | Reading current code, PRs, history |
| Web search / Context7 MCP | 3rd party documentation |

The Coder Subagent

Purpose: The I in RPI. Reads the plan and writes the code.
Hizal Setup: dev_coder agent type, dev_coding session lifecycle. Injected with: identity, project conventions and constraints.
Platform: Terminal coding agent (OpenCode) on the Orchestrator's EC2, in a git worktree.
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Sequence

Start session. Opens a dev_coding Hizal session.
Read the chain. Fetch dev_spec, dev_research, and dev_plan chunks by query keys.
Check memories. Search for memories of similar past work.
Search project context. Check for relevant project chunks. Always before code.
Implement. Write code following the phased plan. At the end of each phase: run linters, tests, build scripts. Fix issues before the next phase.
Output. Either:
- Set spec status to blocked, write blocked_reason
- OR create a PR and a dev_implementation chunk. Contains: PR link, change summary, files modified, test coverage notes. Link to spec and plan chunks with reasons. Update spec status to implemented.
Save memories. Write memory chunks.

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, chunk management, status updates |
| git/source-control | Branching, committing, PRing |

The QA Subagent

Purpose: Verify implementations meet spec. Evidence-based, not vibes-based.
Hizal Setup: dev_qa agent type, dev_verification session lifecycle. Injected with: identity, project conventions, constraints, testing standards.
Platform: Terminal coding agent (OpenCode) on the Orchestrator's EC2, in a git worktree.
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Role and Responsibilities

QA is the hardest subagent to get right. A bad QA agent either rubber-stamps everything (useless) or rejects on trivial style issues (noise). The key: structured acceptance criteria from the plan chunk and evidence-based output.

Sequence

Start session. Opens a dev_verification Hizal session.
Read the chain. Fetch dev_spec, dev_plan, and dev_implementation chunks. Extract acceptance criteria from the plan.
Check out the PR branch. Review the diff against main.
Run the test suite. All existing tests must pass. Note any new test coverage.
Evaluate coverage gaps. If acceptance criteria lack test coverage, write tests. This is the QA agent's primary value-add — it doesn't just check, it improves.
Functional verification (if applicable). If staging is available, run basic E2E checks.
Output. A structured verification report, then either:
- Create a dev_verification chunk — criteria-by-criteria evidence:
```
 Criteria A: ✅ — covered by test_create_user (new)
 Criteria B: ✅ — covered by test_auth_middleware (existing)
 Criteria C: ❌ — endpoint returns 500 on empty input (test added, fix needed)
```
Link to spec and implementation chunks. Update spec status to verified.
- OR create a dev_rejection chunk — details what failed and why. Link to spec and implementation chunks. Revert spec status to planned (back to Coder) or researched (back to Planner) depending on severity.
Save memories. Write memory chunks.

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, chunk management, status updates |
| git/source-control | Checking out PR, reading diff, running tests |
| Web search + browser | E2E testing against staging (if applicable) |

The Delivery Subagent

Purpose: Package verified changes into release branch PRs for human review.
Hizal Setup: dev_delivery agent type, dev_delivery session lifecycle. Injected with: identity, project conventions, deployment procedures.
Platform: Terminal coding agent (OpenCode) on the Orchestrator's EC2.
Models: MiniMax 2.5 Free (opencode/minimax-m2.5-free) — via OpenCode Zen

Sequence

Start session. Opens a dev_delivery Hizal session.
Find verified specs. list_chunks(chunk_type="dev_spec", custom_fields={"status": "verified"}). If none: save memories, end session.
Create or update release branch. Merge all verified PRs into release/vX.Y.Z. Resolve merge conflicts (usually trivial). If non-trivial: set affected spec to blocked.
Review specs. Re-read each included dev_spec. Write release PR description summarizing all changes with links.
Output. Either:
- Create a dev_package chunk — lists all included items, specs, and the release PR link. inject_audience targets the Assistant (who notifies the human). Link to spec and verification chunks. Update all included specs to status packaged.
- OR create a dev_rejection chunk if conflicts can't be resolved. Revert affected spec status to implemented.
On human merge: Monitor CI/CD pipeline. On successful deploy, create a dev_deployment chunk. Link to spec and package chunks. Update all included specs to status deployed.
Save memories.

Human Approval Flow

Delivery creates release PR → writes dev_package chunk
    → inject_audience targets Assistant
    → Assistant notifies human via Telegram
    → human reviews PR on GitHub
    → human merges → CI/CD deploys
    → Delivery writes dev_deployment chunk

Requires: HIZAL-174 — Event triggers (webhook on package creation → notify human automatically)

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, chunk management, status updates |
| git/source-control | Branching, merging, PR management |

The Operations Agent

Purpose: Manage infrastructure, handle incidents, execute rollbacks.
Hizal Setup: dev_operations agent type, dev_operations session lifecycle. Injected with: infrastructure conventions, deployment history, active incidents.
Platform: Persistent agent. Location TBD.
Models: Sonnet 4.6

Incident Flow

Monitoring (Sentry/CloudWatch)
    → event trigger creates dev_incident chunk in Hizal  [HIZAL-174]
    → chunk auto-injects to Operations Agent
    → Operations Agent triages:
        → Critical: roll back, write dev_rollback chunk, notify Assistant → human
        → Non-critical: set relevant spec to blocked, write blocked_reason
    → Hotfix: create new dev_spec with priority=critical, status=new
        → Orchestrator picks up as highest priority on next heartbeat

Push, not poll. Incidents are created via Hizal event triggers (HIZAL-174) — not waiting for agent heartbeats.

Capabilities

Roll back ECS to previous task definition
Revert merge commits
Create high-priority hotfix specs (feed back into RPI pipeline)
Monitor deploy health after releases
Manage infrastructure scaling

Tools

| Tool | Purpose |
|------|---------|
| Hizal MCP | Memory, context, chunk management |
| AWS CLI / infrastructure tools | ECS, EC2, RDS management |
| git/source-control | Revert commits, hotfix branches |
| Channels (Telegram) | Escalation to human via Assistant |

Chunk Type Reference

Artifact Chunks (created by subagents, linked to spec)

| Chunk Type | Created by | Purpose | Custom Fields |
|------------|-----------|---------|---------------|
| `dev_spec` | Assistant or Researcher | **The work item.** Spec + acceptance criteria. Status field drives the entire workflow. | `status`, `priority`, `blocked_reason`, `previous_status`, `ticket_url` |
| `dev_research` | Researcher | What exists in the code, what needs to change. No implementation details. | — |
| `dev_plan` | Planner | Phased implementation with acceptance criteria per phase. | — |
| `dev_implementation` | Coder | PR link, change summary, files modified, test notes. | — |
| `dev_verification` | QA | Evidence-based criteria-by-criteria test results. | — |
| `dev_rejection` | QA or Delivery | What failed, why, root cause, recommendation. | — |
| `dev_package` | Delivery | Release branch PR with all included items. | — |
| `dev_deployment` | Delivery | Deployment record: environment, version, timestamp. | — |

Signal Chunks (created by external systems or Ops)

| Chunk Type | Created by | Purpose |
|------------|-----------|---------|
| `dev_incident` | Event trigger (Sentry/CloudWatch → [HIZAL-174](https://forge.xferops.dev/HIZAL-174)) | Production issue detected |
| `dev_rollback` | Operations Agent | Deployment reverted. Links to deployment + incident. |

Note: dev_blocker is no longer a separate chunk type. Blocked state is tracked via the status and blocked_reason custom fields on dev_spec. See HIZAL-171.

Agent Type Reference

| Agent Type | Session Lifecycle | Persistence | Purpose |
|------------|------------------|-------------|---------|
| `dev_assistant` | `dev_assisting` | Persistent | Human interface, spec drafting, notifications |
| `dev_orchestrator` | `dev_orchestration` | Persistent (heartbeat) | Spec status queries, subagent coordination |
| `dev_researcher` | `dev_research` | Ephemeral | Research existing code + docs |
| `dev_planner` | `dev_planning` | Ephemeral | Create implementation plans |
| `dev_coder` | `dev_coding` | Ephemeral | Write code, create PRs |
| `dev_qa` | `dev_verification` | Ephemeral | Evidence-based verification |
| `dev_delivery` | `dev_delivery` | Ephemeral | Package releases, monitor deploys |
| `dev_operations` | `dev_operations` | Persistent | Infrastructure, incidents, rollbacks |

Session Lifecycle Injection Rules

| Lifecycle | Injects | Notes |
|-----------|---------|-------|
| `dev_assisting` | Latest N memory from self, blocked specs (via inject_audience), pending packages (via inject_audience) | `latest: N` rule per [HIZAL-173](https://forge.xferops.dev/HIZAL-173) |
| `dev_orchestration` | Latest N memory from self, org principles, project conventions, project constraints | Status queries done via `list_chunks`, not injection |
| `dev_research` | Org principles, project conventions, project constraints | Subagent reads spec by query key, not injection |
| `dev_planning` | Org principles, project conventions, project constraints | Subagent reads research by query key |
| `dev_coding` | Project conventions, project constraints | Subagent reads plan by query key |
| `dev_verification` | Project conventions, project constraints, testing standards | Subagent reads implementation chain by query keys |
| `dev_delivery` | Project conventions, deployment procedures | Queries verified specs via `list_chunks` |
| `dev_operations` | Infrastructure conventions, latest N deployment, active incidents (via inject_audience) | Incidents pushed via event triggers |

Chunk Linking

All artifact chunks link back to the spec and to their predecessor artifact using unidirectional links with a mandatory reason:

dev_spec
  ← dev_research (reason: "Research for this spec")
    ← dev_plan (reason: "Plan based on this research")
      ← dev_implementation (reason: "Implementation of this plan")
        ← dev_verification (reason: "Verification of this implementation")
          ← dev_package (reason: "Release including this verified item")
            ← dev_deployment (reason: "Deployment of this release")

Every chunk in the chain can be traced back to its spec. An agent reading any chunk can follow links to understand the full context.

Requires: HIZAL-170 — Chunk linking with mandatory reason

Compute Architecture

┌─────────────────────────────────────────┐
│  Human's Machine (Mac Mini / Laptop)    │
│  ┌───────────────────────────────────┐  │
│  │  Assistant Agent (OpenClaw)       │  │
│  │  - Telegram channel               │  │
│  │  - All projects visible           │  │
│  │  - Never writes code              │  │
│  │  - Creates dev_spec chunks        │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
          │ (Telegram / Hizal)
          ▼
┌─────────────────────────────────────────┐
│  Project EC2 (1 per project)            │
│  ┌───────────────────────────────────┐  │
│  │  Orchestrator Agent (OpenClaw)    │  │
│  │  - Heartbeat-driven               │  │
│  │  - Queries specs by status        │  │
│  │  - Spawns subagents               │  │
│  └───────────────────────────────────┘  │
│                                         │
│  ┌──────────┐ ┌──────────┐ ┌────────┐   │
│  │Researcher│ │ Planner  │ │ Coder  │   │
│  │(worktree)│ │(worktree)│ │(wktree)│   │
│  └──────────┘ └──────────┘ └────────┘   │
│  ┌──────────┐ ┌──────────┐              │
│  │    QA    │ │ Delivery │              │
│  │(worktree)│ │(worktree)│              │
│  └──────────┘ └──────────┘              │
└─────────────────────────────────────────┘
          │ (Hizal API)
          ▼
┌─────────────────────────────────────────┐
│  Hizal (api.hizal.ai)                   │
│  - Context engine + custom fields       │
│  - Single source of truth               │
│  - list_chunks for structured queries   │
│  - Event triggers for push workflows    │
│  - Memory via latest-N injection        │
└─────────────────────────────────────────┘

Hizal Features Required

This workflow depends on Hizal features that are planned but not yet shipped. Each is tracked as a Forge ticket.

| Feature | Ticket | Priority | Status | Unlocks |
|---------|--------|----------|--------|---------|
| **Custom fields on chunk types** | [HIZAL-171](https://forge.xferops.dev/HIZAL-171) | HIGH | Backlog | Spec status tracking, schema validation, structured queries. **The foundation — most other features build on this.** |
| **list_chunks with structured filters** | [HIZAL-172](https://forge.xferops.dev/HIZAL-172) | HIGH | Backlog | Orchestrator queries specs by status. Replaces negative-join workarounds. |
| **Event triggers (webhooks)** | [HIZAL-174](https://forge.xferops.dev/HIZAL-174) | HIGH | Backlog | Push-based incident response, human notifications on package creation, cross-system sync. |
| **Chunk linking with reason** | [HIZAL-170](https://forge.xferops.dev/HIZAL-170) | MEDIUM | Backlog | Artifact chain traceability (spec → research → plan → impl → verify → package → deploy). |
| **latest-N injection predicate** | [HIZAL-173](https://forge.xferops.dev/HIZAL-173) | MEDIUM | Backlog | Automatic rolling memory injection. Eliminates manual un-injection of previous session memory. |
| **Tag-enriched embeddings** | [HIZAL-169](https://forge.xferops.dev/HIZAL-169) | MEDIUM | Backlog | Tags included in vector input. Enables semantic search to find encrypted or sparsely-described chunks. |
| **Encrypted chunks** | [HIZAL-168](https://forge.xferops.dev/HIZAL-168) | LOW | Backlog | Store credentials/secrets in chunks with client-side encryption. |

Implementation Order

HIZAL-171 (custom fields) ──→ HIZAL-172 (list_chunks) ──→ Core workflow functional
                                    │
HIZAL-170 (chunk linking) ─────────┼──→ Full artifact chain traceability
                                    │
HIZAL-173 (latest-N injection) ────┼──→ Automatic memory continuity
                                    │
HIZAL-174 (event triggers) ────────┼──→ Push-based incidents + notifications
                                    │
HIZAL-169 (tag embeddings) ────────┘
HIZAL-168 (encrypted chunks)

Minimum viable workflow: HIZAL-171 + HIZAL-172. With custom fields and list_chunks, the orchestrator can query specs by status and subagents can advance the state machine. Everything else enhances the workflow but isn't blocking.

Architecture Overview

Work Item Lifecycle

Status State Machine

Status Definitions

Custom Fields on dev_spec

Blocked / Unblocked Flow

Rejection Flow

Orchestrator Queries

The Assistant Agent

Role and Responsibilities

Session Lifecycle

Tools

The Orchestrator Agent

Role and Responsibilities

Orchestration Sequence

Tools

Subagent Infrastructure

Directory Structure

Wrapper Script: adh-spawn.sh

Scoped OpenCode Configs

Skills

Hizal API Keys

The Researcher Subagent

Sequence

Tools

The Planner Subagent

Sequence

Tools

The Coder Subagent

Sequence

Tools

The QA Subagent

Role and Responsibilities

Sequence

Tools

The Delivery Subagent

Sequence

Human Approval Flow

Tools

The Operations Agent

Incident Flow

Capabilities

Tools

Chunk Type Reference

Artifact Chunks (created by subagents, linked to spec)

Signal Chunks (created by external systems or Ops)

Agent Type Reference

Session Lifecycle Injection Rules

Chunk Linking

Compute Architecture

Hizal Features Required

Implementation Order

Custom Fields on `dev_spec`

Wrapper Script: `adh-spawn.sh`