DEV Community: Parker

Your AI Agent Doesn't Need More Memory Tools. It Needs to Learn to Introspect.

Parker — Tue, 14 Apr 2026 04:25:34 +0000

The pattern I keep seeing in agent systems:

The main agent has 12 memory-related tool calls available to it. It uses them inconsistently. Sometimes it searches, sometimes it forgets to. Sometimes it writes something worth keeping, sometimes it doesn't. Context quality is a function of discipline, not architecture.

That's not a memory problem. That's a cognitive interface problem.

And I think we've been solving it wrong.

The current model

Right now, if you want your agent to have durable memory, you give it tools:

search_context(query)
write_memory(content)
read_context(id)
get_related(ref)
register_focus(tags)
compact_context()

And then you cross your fingers and hope it uses them correctly.

Sometimes it does. Often it doesn't.

And every one of those tool calls costs tokens. The round-trip to reason about whether to search, what to search for, whether the results are relevant, what to write, what scope to use — that's cognitive tax on every single turn.

That tax compounds fast.

There's a better abstraction

What if the agent didn't have to think about any of that?

What if instead of a bag of memory tools, the agent just had one interface to its own memory system — and that interface was called Introspect?

introspect("I'm about to help Parker with System-1 architecture.
What prior decisions, open questions, and preferences should I
keep in mind before I respond?")

That's it.

Not "search, read, filter, rank, decide if relevant." Just introspect.

The deeper shift is this: the agent stops acting like the maintainer of its own memory system and starts acting like the consumer of a subconscious built for continuity.

The agent asks its subconscious a question in natural language. The subconscious returns grounded, relevant context. The agent moves on.

This is what we're building with System-1 — a subconscious runtime for AI agents with Introspection as its primary interface.

Why introspection is a different thing than search

This is subtle but important.

Search is: "give me documents that match this query."

Introspection is: "tell me what I should know about this, including things I don't know to ask for."

When an agent introspects, it might ask:

"what am I forgetting?"
"what context should I check before replying?"
"who is this person and what patterns exist in our work?"
"reconnect me to what I was doing last session"

Those aren't search queries. They're cognitive self-checks.

Introspection is closer to how a human accesses prior knowledge — not by keyword, but by relevance to the current moment.

And that distinction changes what the underlying system has to do. It needs:

multi-stage retrieval, not one-shot lookup
evidence-grounded synthesis, not raw result dumps
preloaded ambient context at session start, not cold retrieval every time
iterative follow-up if the first pass is incomplete

The token math

This framing also has real cost implications.

Today, if you expose 10 memory tools to an agent:

the model must reason about all 10 in its decision loop
it pays tokens to decide which to call
it pays tokens on each tool call
it pays tokens to evaluate whether the results are useful
it often gets it wrong and pays again

With Introspection as a single clean interface:

one tool call replaces many
the subconscious layer handles routing, retrieval strategy, and synthesis internally
the main model gets high-signal output, not raw backend results
token budget goes to the actual task instead of memory plumbing

This is a real win. Not marginal. Meaningful.

A well-designed subconscious layer should reduce token spend on memory operations significantly while improving recall quality at the same time.

What the subconscious actually does

The interface is simple. The system beneath it is not.

System-1 handles:

Substrate observation
It watches the agent's runtime activity — messages, tool calls, completions — continuously in the background. The main agent never has to trigger this.

Conservative extraction
At every turn, System-1 asks: is anything in this turn worth remembering? Often the answer is no. That's fine. Abstention is the default. When something is worth keeping, it proposes a candidate artifact with evidence and provenance attached.

Waking Mind on startup
At the start of every session, before the agent does anything, System-1 preloads relevant ambient context and generates a high-signal orientation layer. The agent wakes up knowing who it is, who the user is, what project matters, and what it was probably working on last.

Introspection on demand
When the agent needs to go deeper, it calls introspect(...). System-1 consults preloaded context first, performs iterative backend retrieval if needed, synthesizes grounded output, and returns a natural-language answer.

The main agent talks to System-1 in English. System-1 handles everything else.

The hard constraint

There's one rule we've been rigidly designing around:

System-1 is allowed to remember, surface, and synthesize.
It is not allowed to fictionalize.

A subconscious that hallucinates is worse than no subconscious. It feels coherent. It's wrong. The agent acts on it.

So the whole architecture is built around this discipline:

extraction is conservative — most turns produce nothing
every durable artifact requires provenance and grounding evidence
synthesis must remain traceable to source
uncertainty must survive — the system should say "unclear" rather than confabulate
inspectability is architectural, not optional

This is the hard part of the problem. The clean interface is the easy part.

One more thing

System-1 is being built as a backend-agnostic subconscious runtime.

It works with a local file-based backend for easy adoption. It works best with Hizal — a structured memory system that maps naturally onto the System-1 model with scoped storage, deterministic ambient injection, and rich retrieval.

But the key architectural bet is this:

Introspection is an abstraction layer, not a thin wrapper.

If the agent experience changes when you swap backends, the abstraction failed.
If the agent can introspect with the same interface against a file backend or Hizal and get equally coherent output, the abstraction worked.

The bigger picture

Agents don't need more memory tools.

They need a better relationship to memory.

The current state is: agent as its own memory system maintainer, manually juggling reads and writes across every turn.

The alternative: agent as consumer of a subconscious that handles continuity, context surfacing, and grounded recall as infrastructure.

Introspection is that interface.

If you're building agents and find yourself burning tokens on memory choreography, or watching agents forget context they should obviously have, or struggling to make memory feel natural and coherent — this is the problem we're solving.

Still early. Still building. I'm sure we'll learn things the hard way. But the direction feels right, and the ambition is to make agent continuity feel less like plumbing and more like cognition.

Agentic Development with Hizal

Parker — Wed, 08 Apr 2026 20:03:06 +0000

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.

DEV Community: Parker

Your AI Agent Doesn't Need More Memory Tools. It Needs to Learn to Introspect.

The current model

There's a better abstraction

Why introspection is a different thing than search

The token math

What the subconscious actually does

The hard constraint

One more thing

The bigger picture

Agentic Development with Hizal

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`