It happened again. I came to the end of the month, and I had not (nearly) used up all of my GitHub Copilot "AI Credits", which put me in the luxurious place of having "unlimited" agentic assistance at my disposal, albeit for just a short period of time (3 hours). Fable5 and I went to town doing an initial implementation of "base" SMCC - State Management of Compiled Context. Sorry, nobody helped me come up with a better name and now there is a GitHub repo by that name. 🤣 By the way, I used up 35% of a month's worth of AI credits in 3 hours, so be really careful using that very powerful model!

It was kind of a weird meta-experience building this. I used a combination of my old "human clipboard Mixture of Experts" workflow to start, but then we switched to using SMCC during its creation, the so-called 'fly the plane while building it' exercise.

After creating an ARCHITECTURE.md file with GPT5, I booted the repo and did an initial commit with the file. The normal "you (Fable5) are a co-equal design partner, what do you think?" exercise ensued and we refined the design to (3-way) mutual satisfaction.

A key bootstrap question I had was: "How do you create a base SMCC repo of assets and how do you transport those assets to the actual code repo? We settled on a "sidecar" strategy, namely a .smcc folder in the repo containing:

The .smcc sidecar

The project state lives alongside the source tree in a .smcc/ directory:

• project.yaml — project identity, configuration, and top-level metadata
• state/ — authoritative shared project state
  • goals/ — what the project is trying to accomplish
  • requirements/ — capabilities and behaviors the solution must provide
  • constraints/ — boundaries the implementation must respect
  • decisions/ — architectural and implementation decisions already made
  • questions/ — unresolved questions that still need answers
  • findings/ — durable facts learned during the work
• tasks/ — the task DAG and per-task state (TASK-001, TASK-002, ...)
• contexts/ — compiled context packages presented to an agent for a particular task
• proposals/ — structured changes proposed by an agent before they become authoritative state
• history/ — records of proposal review, acceptance, rejection, and other state transitions
• artifacts/ — outputs produced during execution that should be retained with the project

The project.yaml file is simple:

# SMCC project sidecar configuration (non-versioned config, not an authoritative state object)
schema_version: 1
name: smcc
description: >-
  State Management of Compiled Context. Typed, versioned, dependency-aware project state for coding agents. The smcc repository is the first SMCC-managed project.
goal_refs:
  - GOAL-001
created_at: "2026-09-30"

Fable started by creating 5 constraints, 12 decisions, 1 goal and 4 tasks. Before a single line of code was written, of course.

Constraints

The iterative design session consumed the ARCHITECTURE.md as originally proposed and went through a series of questions, e.g. what language? (Python or TypeScript).

This illustrates the contents of CON-001.yaml:

id: CON-001
type: Constraint
schema_version: 1
version: 2
status: accepted
scope: project
title: Python is the primary implementation language
statement: >-
  Primary implementation language is Python. TypeScript is acceptable only where it provides concrete value for VS Code integration. Other languages require a compelling reason.
created_at: "2026-09-30"
updated_at: "2026-09-30"
source: bootstrap/EHO
supersedes: []

• CON-002 - file-based, no database in v1
• CON-003 - context selection is explicit only in v1
• CON-004 - v1 scope exclusions (deferred work)
• CON-005 - Agents propose; humans accept consequential state transitions

CON-005 is a key core principle in the design. CON-003 is basically saying "no fancy AI model interactions" (in V1).

Key design decisions

The 12 decisions are too detailed for this post (I don't want to bore you to sleep) so I will summarize them. The key narrative here is that these decisions define the data/control-flow story.

• Project state is explicit, typed, and versioned. Goals, requirements, constraints, decisions, questions, and findings are authoritative state. Each object has a current version; Git retains its history.

• Tasks and project state are different things. A task has dependencies on other tasks, but separately declares which pieces of authoritative state it needs as context. This keeps execution ordering distinct from information dependencies.

• Agent context is compiled, not assembled ad hoc. SMCC deterministically builds a task-specific context from the required state and dependency results, recording exactly which versions were supplied to the agent.

• Agent output does not directly mutate authoritative state. Task results are persistent records, and changes to project state are made through explicit proposals that can be accepted or rejected independently.

• Provenance is first-class. Compiled contexts, task results, state versions, and Git information preserve the chain from what the agent was told, through what it did, to what eventually became authoritative state.

• The state graph is validated as a system. SMCC checks schemas, references, task-DAG integrity, and context provenance rather than relying on convention and hoping the repository remains coherent.

Two other things are worth mentioning. First, Git is provenance, not the SMCC transaction mechanism. When a task is complete, its commit SHA is recorded in the RESULT-nnn.yaml file. Second, compiled contexts are retained, making it easy to inspect exactly what an agent saw.

Goals

The yaml file is self-explanatory:

id: GOAL-001
type: Goal
schema_version: 1
version: 1
status: accepted
title: Build the SMCC v1 vertical slice
statement: >-
  Build the first usable SMCC vertical slice: explicit authoritative project state, a task DAG, deterministic task-specific context compilation with provenance, structured agent results, state-change proposals, human accept/reject transitions, and dependency-aware invalidation — all file-backed, diffable, and inspectable in the repository. The smcc repository manages itself with this system as it is built.
created_at: "2026-09-30"
updated_at: "2026-09-30"
source: bootstrap/EHO
supersedes: []

"... manages itself with this system as it is built" is the 'flying the plane while building it' part.

Tasks

Tasks, at least in this instance, comprised the work described in GOAL-001. I'll paste TASK-001 in its entirety and then discuss the others in summary.

id: TASK-001
type: Task
schema_version: 1
version: 5
status: accepted
title: Typed state model and file persistence
goal: >-
  Implement Pydantic schemas for the v1 SMCC objects (Goal, Requirement, Constraint, Decision, Question, Finding, Task, Result, Proposal) and file-backed load/validate/save that round-trips the bootstrap fixture in .smcc/.
task_dependencies: []
context_refs:
  - DEC-001
  - DEC-002
  - DEC-009
  - DEC-010
constraints: []
acceptance_criteria:
  - Every SMCC YAML data file in .smcc/ loads and validates without error; non-SMCC files such as .gitkeep are ignored by the store rather than treated as malformed state.
  - Objects round-trip (load then save) without semantic change.
  - Schema violations produce actionable validation errors identifying file, field, and cause.
  - Serialized objects carry schema_version and the common metadata fields.
  - accepted_result is non-null exactly when a Task's status is accepted (schema invariant).
  - No database or non-file persistence is introduced.
assigned_agent: null
outputs: []
accepted_result: RESULT-001
review_state: null
created_at: "2026-09-30"
updated_at: "2026-09-30"
source: bootstrap/EHO
supersedes: []

The "SMCC v1 vertical slice" was a simple linear set of work. In more complex projects, task_dependencies will define the graph. context_refs explicitly name the authoritative state required for the task. This is intended to minimize task drift or context loss since the exact set is defined and hopefully smaller than all possible context (the "one long transcript" problem).

• TASK-001 creates the basic schema and file structure
• TASK-002 implements schema validation and internal consistency
• TASK-003 implements the context compiler (with provenance frontmatter)
• TASK-004 implements staleness detection for compiled contexts

The initial bootstrap produced four implementation tasks. A fifth, TASK-005, was added to complete the proposal → accept/reject lifecycle. At the end of this session the first four were complete, with that lifecycle work remaining. What is interesting about this is SMCC itself discovered additional work while it was being built.

Workflow

Since the initial task graph was so simple (four linear tasks), I'll say a little about the workflow cycle.

A TASK has 8 lifecycle statuses:

class TaskStatus(str, Enum):
    proposed = "proposed"
    ready = "ready"
    in_progress = "in_progress"
    blocked = "blocked"
    review = "review"
    accepted = "accepted"
    rejected = "rejected"
    superseded = "superseded"

The workflow here was a simple progression:

proposed → ready → in_progress → review → accepted.

It's easy to imagine how the other TaskStatus values would be used, but they weren't necessary in this first go-around.

All tasks started life as proposed and then as work progresses, a particular task that is queued for work changes to ready. When the agentic coding session starts, the agent changes the status to in_progress and when complete changes it to review (it also creates a RESULT-nnn.yaml file). At that point, a human-in-the-loop event occurs and the human (me in this case) performs a review of the changes and any proposals and changes the status to either accepted or rejected. In a simple linear sequence of tasks such as this, only one task was in review at a time.

One note about the RESULT-nnn.yaml file. One of its sections has unresolved_questions which can end up populating the questions node in the .smcc sidecar. And in fact we did create a QUESTION-001.yaml file in this session. ("Should validate flag in_progress/review tasks with non-accepted dependencies?").

At this point, SMCC has gone from being an architecture document to managing the state of its own implementation.

A substantial part of the v1 'slice' is now complete. The next step is to experience this workflow in a real coding project. This would have been really helpful in my philatelic machine vision project, but it's a bit late in its life cycle to introduce this across its entirety but may be appropriate for potential future work. I'm currently searching for a less complicated and ambitious project to take this for a real-world spin. I've always wanted to create a graphical simulation of "murmurations" and perhaps that will be an appropriate first tire-kicking project for SMCC.

The GitHub repo is currently private while it is in its "wet paint" stage. It's clear, though, that something like this that "exports" this kind of state structure with state changes and validations in sidecar-fashion must be public. I want to spin this through a couple of those real-world problems before I do that. But, in the meantime, if you want to get access to the repo, get in touch, I will be happy to add you.

In my next SMCC post, I will describe a question I had as soon as the v1 slice was done. "How does this compose with Clarity-Agent"? 🙂