How agents communicate

JSON artifacts on disk. No API. No message queue. Just files.

Directory structure

Every phase writes its output to a predictable location:

.nanostack/
├── think/
│   └── artifact.json
├── plan/
│   └── artifact.json
├── review/
│   └── artifact.json
├── qa/
│   └── artifact.json
├── security/
│   └── artifact.json
├── ship/
│   └── artifact.json
├── sprint/
│   ├── state.json
│   └── locks/
├── journals/
└── know-how/
    ├── bugs/
    ├── patterns/
    └── decisions/

The directory name matches the phase name. Custom phases get their own directories following the same convention.

What is in an artifact

Every artifact follows a common structure, regardless of which phase produced it:

{
  "phase": "review",
  "timestamp": "2026-03-28T14:32:00Z",
  "agent": "claude-code",
  "intensity": "standard",
  "summary": "2 issues found, 1 auto-fixed, 1 needs input",
  "findings": [
    {
      "type": "issue",
      "severity": "medium",
      "file": "src/routes/streaks.ts",
      "line": 42,
      "message": "Duplicate check-in on same day not handled",
      "confidence": 0.82,
      "auto_fixed": false
    }
  ],
  "context_checkpoint": {
    "files_analyzed": 6,
    "total_lines": 847,
    "git_sha": "a1b2c3d"
  },
  "integrity": {
    "sha256_post_redaction": "e5f6g7h8...",
    "secrets_redacted": 0
  }
}

Core fields

• phase — which skill produced this artifact
• timestamp — ISO 8601 when the artifact was saved
• agent — which AI agent ran the phase
• intensity — quick, standard, or thorough
• summary — one-line human-readable description of results
• findings — array of structured results (issues, suggestions, tests, etc.)

context_checkpoint

The checkpoint captures the state of the codebase when the phase ran. This enables crash recovery: if an agent dies mid-phase, a new agent can read the checkpoint and decide whether to re-run or resume. The git SHA anchors the analysis to a specific commit so results stay meaningful even if the code changes between phases.

integrity

The integrity block contains the SHA-256 hash of the artifact content and a count of redacted secrets. Skills that read artifacts can verify the hash to detect corruption or tampering.

How skills read artifacts

Skills use bin/find-artifact.sh to locate and read artifacts:

# Find the most recent artifact for a phase
find-artifact.sh review

# Find artifact with integrity check
find-artifact.sh review --verify

# Find all artifacts for the current sprint
find-artifact.sh --all

The script handles the path resolution, integrity verification, and error cases (missing artifact, failed integrity check). Skills never read artifact files directly; they go through the script.

Project-scoped

Artifacts live in the project's .nanostack/ directory. They are not global. If you work on two projects, each has its own artifact history. This is intentional: a security finding for project A is irrelevant to project B.

The .nanostack/ directory should be in your .gitignore. Artifacts contain analysis output that may reference file contents, and they can grow large over multiple sprints.

Context checkpoints for crash recovery

If an agent crashes during a phase, the checkpoint from the previous phase is still on disk. A new agent can read it to understand the current state:

# Agent 2 picks up after Agent 1 crashed during review
$ sprint.sh status
review: stale (pid 42399 not running)

$ sprint.sh claim review
Reclaimed stale lock: review

# The agent reads the plan artifact for context
$ find-artifact.sh plan
{
  "planned_files": [...],
  "context_checkpoint": {
    "git_sha": "a1b2c3d"
  }
}

# Verifies the code hasn't changed since planning
$ git rev-parse HEAD
a1b2c3d  ← matches checkpoint, safe to proceed

If the git SHA does not match, the agent knows the code changed between phases and can flag that the plan may be stale.