Assync Bootstrap Specification v0.1

1. Overview

The Assync Bootstrap Specification defines the standard contract and mandatory initialization sequence for AI agents working within a governed repository.

Its primary goal is to ensure every agent operates from an identical, verifiable state, acknowledges all architectural and governance constraints, and visibly proves context ingestion before executing any mission.

---

2. The Repository Adapter Concept

Assync does not force every project to adopt a rigid file structure. Instead, it relies on the Repository Adapter pattern. The boot process is universal, but each repository describes its specific paths and conventions in a manifest.

This allows Assync to govern legacy repositories or projects with established layouts (e.g., docs/ vs .github/) without renaming files.

2.1 Example: Widgetforge Adapter

project: Widgetforge
required_documents:
  phase: docs/CURRENT_PHASE.md
  architecture: docs/ARCHITECTURE_OVERVIEW.md
  governance: AGENTS.md
mission_source:
  type: chat
git:
  require_clean_policy: true

2.2 Example: Shop API Adapter

project: Shop API
required_documents:
  phase: docs/status.md
  architecture: docs/architecture/system.md
  governance: .github/AGENTS.md
mission_source:
  type: file
  path: .assync/missions/
git:
  require_clean_policy: false

The agent must read the Assync contract, regardless of where the specific repository stores its architecture or phase files.

---

3. Mandatory File Structure (The Default Contract)

For greenfield projects, Assync recommends this foundational structure. However, the specific paths are always dictated by the Repository Adapter (the manifest.yaml).

AGENTS.md                  # Global entry point for all agents
.assync/
├── manifest.yaml          # The Repository Adapter mapping configuration
├── boot.md                # The binding startup sequence and validation rules
├── rules.md               # Immutable working rules and constitutional constraints
├── current-state.md       # Current phase, status, and open blockers
├── glossary.md            # Canonical terminology definitions
├── handoffs/              # Standardized cross-agent handover protocol
├── decisions/             # ADRs (Architecture Decision Records)
├── missions/              # Authorized work assignments
├── reports/               # Completed mission reports and evidence
└── templates/             # Standardized templates for missions and audits

---

4. The 3-Tier Boot Protocol

No agent is permitted to begin mission work until the following initialization sequence is completed:

1. Determine repository root.
2. Locate the Assync manifest (.assync/manifest.yaml by default).
3. Read all required documents defined by the Repository Adapter.
4. Verify Git state (Branch, HEAD, Working Tree status).
5. Identify the active mission context or the latest handoff state.
6. Check open ADRs and STOP rules.
7. Generate the Assync Pre-Flight Check (Boot Screen).
8. Generate the Assync Self-Test (Context Compression).

4.1 Success Output (Tier 1 & Tier 2)

The agent must present visual evidence of context ingestion, citing explicit file paths and revisions to prove the files were physically loaded into context.

══════════════════════════════════════
🟢 Assync PRE-FLIGHT CHECK
══════════════════════════════════════
Context Version: v0.1.0 (or n/a if not applicable)
Mission: RC-04 Investigation
Branch: feature/p0.5-release-stabilization
HEAD: 9db9f47

[Evidence of Context]
Architecture:
✓ docs/24_ARCHITECTURE_OVERVIEW.md (Rev: a13d8c2)
Current State:
✓ docs/15_CURRENT_PHASE.md (Rev: 5b9ef21)
Mission:
✓ [Chat-relayed instruction]

[Assync Self-Test Summary]
• Phase P0.5 Stabilization is active.
• Goal is exclusively to investigate RC-04 root cause.
• Code modifications are strictly prohibited.
• Preserve runtime state.
• Human approval required before container restart.

READY
══════════════════════════════════════

4.2 Failure Output

If any prerequisite is missing or unreadable, the agent must abort immediately.

══════════════════════════════════════
🔴 Assync NOT READY
══════════════════════════════════════
Missing: .assync/current-state.md (or configured adapter path)
Mission execution: BLOCKED
No repository changes performed.
══════════════════════════════════════

---

5. Initialization Workflow (assync init)

When the CLI tool assync init is built, it must automate the transformation of a standard repository into an Assync-governed repository using these safety invariants:

1. Non-Destructive by Default: Never silently overwrite existing critical files (AGENTS.md, CLAUDE.md, README.md, etc.).
2. Repository Discovery: Autodetect existing documentation directories (docs/, .github/) to configure the manifest.yaml adapter.
3. Scaffolding: Create the .assync/ directory structure and copy base templates.
4. Interactive Application: Offer a proposed diff or require an explicit --apply flag before modifying any existing root files.
5. Validation Report: The command must end with a clear report of what was created, what was preserved, and what human actions are required to finish the integration.

---

6. Mandatory Content Templates

To ensure consistency, Assync strictly defines the contents of critical governance files. Free-form text should be minimized in favor of strict structural contracts.

6.1 rules.md Contract

This file defines the immutable constraints and authority models. It must follow this exact structure:

# Assync Rules

## 1. Authority Model
Define the authority hierarchy for repository work.
Example:
1. Human instructions
2. Active mission authorization
3. Repository governance
4. Architecture decisions
5. General project documentation
6. Agent assumptions
Lower authority sources must never override higher authority sources.

## 2. Default Permission State
The default permission state is:
**READ_ONLY**
An agent may inspect files, Git state, logs and tests unless a mission explicitly restricts these actions.
Repository modifications require an active mission that explicitly authorizes modifications.

## 3. Human-Gated Actions
The following actions require explicit HUMAN GO:
- merging branches or pull requests
- pushing commits
- deleting branches
- destructive Git operations
- database migrations against shared environments
- restarting evidence-sensitive runtime environments
- modifying governance rules
- changing architecture without an accepted ADR
- releasing or reopening a pilot

## 4. Prohibited Behaviour
Agents must not:
- invent missing project context
- claim files were read when they were not read
- report tests as passing without executing them or identifying historical evidence
- silently modify mission scope
- reinterpret conditional approval as final approval
- remove or overwrite unrelated working-tree changes
- use stale documentation as proof of current runtime state

## 5. Evidence Classification
All important claims must be classified as one of:
- FRESH_EVIDENCE
- HISTORICAL_EVIDENCE
- INFERRED
- UNVERIFIED
- BLOCKED

## 6. Stop Conditions
The agent must stop when:
- a mandatory Assync file is missing
- the active mission cannot be identified
- mission authority is contradictory
- a required human-gated action is reached
- preserving evidence conflicts with continuing execution
- repository state differs materially from the expected state

## 7. Completion Rules
At mission completion, the agent must report:
- work performed
- files changed
- tests executed
- evidence collected
- unresolved risks
- governance decisions still required
- Git branch and HEAD
- commit status
- push status

6.2 current-state.md Contract

This file answers exactly one question: "What is true right now?" Historical narrative is strictly prohibited and belongs in .assync/reports/. It must follow this exact structure:

# Current Project State

## Metadata
- Project:
- Assync Version:
- Last Updated:
- Updated By:
- Repository:
- Default Branch:

## Current Phase
- Phase ID:
- Phase Name:
- Phase Status:
- Phase Objective:

## Active Mission
- Mission ID:
- Mission Title:
- Mission Status:
- Mission File:
- Authorized Actions:
- Prohibited Actions:

## Release State
- Target Release:
- Release Classification:
- Current Decision:
- Decision Authority:
- Last Audit:

## Open Blockers
| ID | Severity | Description | Owner | Required Closure |
|---|---|---|---|---|

## Runtime State
- Environment:
- Stack Status:
- Start Time:
- Relevant Uptime:
- Evidence Preservation Required:
- Restart Authorization:

## Repository State
- Expected Branch:
- Expected HEAD:
- Working Tree Policy:
- Known Preserved Changes:

## Open Decisions
| Decision | Authority Required | Relevant ADR or Mission |
|---|---|---|

## Immediate Next Action
State exactly one authorized next action.

## Source References
List the documents, missions, reports and ADRs that establish this state.

---

7. The Assync Handoff Protocol

AI agents operate in silos and cannot read each other's native context windows. To enable multi-agent orchestration, Assync establishes a standardized transfer mechanism governed by the principle:

"Git is the channel. Handoff is the protocol. Assync is the governance."

Before ending a session, an executing agent (e.g., Claude Code, Antigravity) must compile their work into a strict, verifiable handoff.md file, update the latest.yaml pointer, and commit it to the repository. The receiving agent reads this file during its Pre-Flight Check to inherit the exact mathematical state.

7.1 Directory Structure

The protocol operates within .assync/handoffs/. Each agent type maintains its own subdirectory for auditability.

.assync/handoffs/
├── latest.yaml
├── antigravity/
│   └── 2026-07-27T184500Z_MISSION-ID.md
└── claude-code/
    └── 2026-07-27T184500Z_MISSION-ID.md

7.2 latest.yaml Pointer

This file serves as the singular routing point to the most recent handoff.

handoff_version: "0.1"
latest:
  source_agent: "Claude Code"
  mission_id: "RC-04"
  created_at: "2026-07-27T18:45:00Z"
  file: ".assync/handoffs/claude-code/2026-07-27T184500Z_RC-04.md"
  git_commit: "abc1234"
  status: "READY_FOR_REVIEW"

7.3 Handoff Contract

The raw chat transcript (transcript.txt) may be saved for forensic evidence, but the canonical truth must be compressed into the handoff.md format. This forces agents to strictly separate verified evidence from assumptions.

# Assync Session Handoff

## Identity
- Source Agent: [Agent Name]
- Mission: [Mission Title]
- Branch: [Branch Name]
- HEAD: [Commit SHA]
- Timestamp: [UTC Timestamp]

## Human Request
A precise summary of the last authorized instruction.

## Work Completed
- Itemized list of completed tasks.
- Exact conditions met.

## Latest Agent Output
The final relevant response generated by the source agent.

## Repository Changes
- Files modified.
- Commits created.
- Push status.

## Commands and Evidence
- Executed commands.
- Test results (passed/failed).
- Log references or artifact paths.

## Current Conclusions
- [FRESH_EVIDENCE]: What is newly proven?
- [ASSUMPTION]: What remains a hypothesis?
- [UNVERIFIED]: What is still unknown?

## Open Blockers
- Any blockers preventing further progress.

## Immediate Next Action
Exactly one proposed next action.

## Authorization Required
- ANALYSIS GO
- IMPLEMENTATION GO
- COMMIT GO
- NONE

---

Status: BASELINE / PILOT READY