Skip to content

docs: reconcile secondary docs to v4 numbering/phases #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
boshu2 merged 1 commit into from
Jun 7, 2026
Merged

docs: reconcile secondary docs to v4 numbering/phases #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .github/ISSUE_TEMPLATE/pattern-proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,15 @@ assignees: ''
- [ ] I: Context Is Everything
- [ ] II: Track Everything in Git
- [ ] III: One Agent, One Job
- [ ] IV: Research Before You Build
- [ ] V: Validate Externally
- [ ] VI: Lock Progress Forward
- [ ] VII: Extract Learnings
- [ ] VIII: Compound Knowledge
- [ ] IX: Measure What Matters
- [ ] X: Isolate Workers
- [ ] IV: Enforce Least Privilege
- [ ] V: Research Before You Build
- [ ] VI: Isolate Workers
- [ ] VII: Validate Externally
- [ ] VIII: Lock Progress Forward
- [ ] IX: Extract Learnings
- [ ] X: Compound Knowledge
- [ ] XI: Supervise Hierarchically
- [ ] XII: Harvest Failures as Wisdom
- [ ] XII: Measure Outcomes

---

Expand Down
38 changes: 19 additions & 19 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,22 +28,22 @@ For general autonomous agents, see [12-Factor Agents](https://github.com/humanla

The model is not the problem. The operations are. We apply decades of DevOps and SRE methodology to how people work with AI agents:

| DevOps / SRE Principle | Our Application (v3 Factor) |
| DevOps / SRE Principle | Our Application (v4 Factor) |
|------------------------|-----------------------------|
| Configuration Management | **I. Context Is Everything** -- manage what enters the context window like you manage what enters production |
| Infrastructure as Code | **II. Track Everything in Git** -- prompts, learnings, workflows as versioned artifacts |
| Single Responsibility | **III. One Agent, One Job** -- each agent gets a scoped task and fresh context |
| Design Reviews | **IV. Research Before You Build** -- understand the problem space before generating code |
| Zero-Trust Verification | **V. Validate Externally** -- no agent grades its own work, ever |
| Continuous Delivery | **VI. Lock Progress Forward** -- validated work ratchets and cannot regress |
| Post-Mortems | **VII. Extract Learnings** -- every session produces two outputs: the work and the lessons |
| Observability & Feedback Loops | **VIII. Compound Knowledge** -- the knowledge flywheel that makes sessions smarter over time |
| SLOs & Error Budgets | **IX. Measure What Matters** -- track fitness toward goals, not activity metrics |
| Process Isolation | **X. Isolate Workers** -- each worker gets its own workspace and zero shared mutable state |
| Least Privilege / Zero-Trust Access | **IV. Enforce Least Privilege** -- each agent gets the minimum permissions its job requires, nothing more |
| Design Reviews | **V. Research Before You Build** -- understand the problem space before generating code |
| Process Isolation | **VI. Isolate Workers** -- each worker gets its own workspace and zero shared mutable state |
| Zero-Trust Verification | **VII. Validate Externally** -- no agent grades its own work, ever |
| Continuous Delivery | **VIII. Lock Progress Forward** -- validated work ratchets and cannot regress |
| Post-Mortems | **IX. Extract Learnings** -- every session produces two outputs: the work and the lessons |
| Observability & Feedback Loops; Blameless Post-Mortems | **X. Compound Knowledge** -- the knowledge flywheel that makes sessions smarter over time; failed attempts are data, not waste |
| Escalation Hierarchies | **XI. Supervise Hierarchically** -- escalation flows up, never sideways |
| Blameless Post-Mortems | **XII. Harvest Failures as Wisdom** -- failed attempts are data, not waste |
| SLOs & Error Budgets | **XII. Measure Outcomes** -- track fitness toward goals, not activity metrics |

**The core insight:** Better operations make the same model perform dramatically better. Knowledge compounding (Factor VIII) is the differentiator that no amount of model improvement replaces.
**The core insight:** Better operations make the same model perform dramatically better. Knowledge compounding (Factor X) is the differentiator that no amount of model improvement replaces.

```
Ad-hoc: Prompt agent -> Hope for good output -> Repeat from scratch
Expand All @@ -56,10 +56,10 @@ Contributions map to the tier they strengthen:

| Tier | Factors | Focus |
|------|---------|-------|
| **Foundation (I-III)** | Context, Git, Scoping | Non-negotiable basics, zero tooling required |
| **Workflow (IV-VI)** | Research, Validation, Ratcheting | The discipline that separates hoping from operating |
| **Knowledge (VII-IX)** | Extraction, Compounding, Measurement | Where sessions get measurably smarter over time |
| **Scale (X-XII)** | Isolation, Supervision, Failure Harvesting | Multi-agent orchestration (advanced, optional) |
| **Foundation (I-IV)** | Context, Git, Scoping, Least Privilege | Non-negotiable basics, zero tooling required |
| **Workflow (V-VIII)** | Research, Isolation, Validation, Ratcheting | The discipline that separates hoping from operating |
| **Knowledge (IX-X)** | Extraction, Compounding | Where sessions get measurably smarter over time |
| **Scale (XI-XII)** | Supervision, Measurement | Multi-agent orchestration and outcome tracking (advanced) |

---

Expand All @@ -72,9 +72,9 @@ The best contributions add new operational patterns that practitioners can apply
Patterns can address any tier. Some high-value categories:

- **Context management patterns** (Factor I) -- techniques for loading, pruning, and structuring context windows
- **Workflow discipline patterns** (Factors IV-VI) -- research templates, validation checklists, ratcheting mechanisms
- **Knowledge compounding patterns** (Factor VIII) -- extraction workflows, quality gates, retrieval strategies, decay management
- **Failure harvesting patterns** (Factor XII) -- techniques for capturing and indexing what did not work
- **Workflow discipline patterns** (Factors V-VIII) -- research templates, validation checklists, ratcheting mechanisms
- **Knowledge compounding patterns** (Factor X) -- extraction workflows, quality gates, retrieval strategies, decay management
- **Failure harvesting patterns** (Factor X) -- techniques for capturing and indexing what did not work

**Operational pattern checklist:**

Expand Down Expand Up @@ -216,7 +216,7 @@ Our skills and patterns can always be sharper. Contributions that improve operat

### 5. Share Knowledge Compounding Workflows

Factor VIII (Compound Knowledge) is the hero differentiator. Contributions that demonstrate real knowledge compounding workflows are especially valuable:
Factor X (Compound Knowledge) is the hero differentiator. Contributions that demonstrate real knowledge compounding workflows are especially valuable:

- How you structure `learnings.md` files
- Quality gating criteria for extracted knowledge
Expand Down Expand Up @@ -280,7 +280,7 @@ Discussion first:

| Quality | Good | Bad |
|---------|------|-----|
| **Actionable** | "Add this check before commit to enforce Factor V" | "Agents could be better" |
| **Actionable** | "Add this check before commit to enforce Factor VII" | "Agents could be better" |
| **Grounded** | Maps to specific factor(s) and tier | Generic agent advice |
| **Evidence-based** | Shows real session improvement | Theoretical claims |
| **Portable** | Works without specific tooling | Requires proprietary setup |
Expand Down
2 changes: 1 addition & 1 deletion GOALS.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ goals:
- id: factor-naming-consistent
description: "Factor files are numbered 01-12 and filenames reflect the new factor titles"
check: |
expected="01-context-is-everything 02-track-everything-in-git 03-one-agent-one-job 04-research-before-you-build 05-validate-externally 06-lock-progress-forward 07-extract-learnings 08-compound-knowledge 09-measure-what-matters 10-isolate-workers 11-supervise-hierarchically 12-harvest-failures-as-wisdom"
expected="01-context-is-everything 02-track-everything-in-git 03-one-agent-one-job 05-research-before-you-build 07-validate-externally 08-lock-progress-forward 09-extract-learnings 10-compound-knowledge 12-measure-outcomes 06-isolate-workers 11-supervise-hierarchically 10-compound-knowledge"
count=0
for name in $expected; do
[ -f "factors/${name}.md" ] && count=$((count+1))
Expand Down
69 changes: 35 additions & 34 deletions docs/00-SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ see [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) by Dex Ho

## The 12 Factors

### Foundation (I--III) -- Start Here
### Prepare (I--III) -- Start Here

Non-negotiable basics. Zero tooling required. Get these wrong and nothing else matters.

Expand All @@ -45,34 +45,29 @@ Non-negotiable basics. Zero tooling required. Get these wrong and nothing else m
| **[II](../factors/02-track-everything-in-git.md)** | **Track Everything in Git** | If it is not in git, it did not happen -- learnings, decisions, and knowledge live alongside code. |
| **[III](../factors/03-one-agent-one-job.md)** | **One Agent, One Job** | Each agent gets a scoped task and fresh context; never reuse a saturated window. |

### Flow (IV--VI) -- The Discipline
### Bound (IV--VI) -- The Discipline

How work flows through agents. The discipline that separates "prompting and hoping"
How work is bounded before agents run. The discipline that separates "prompting and hoping"
from a reliable operating model.

| # | Factor | One-Line Rule |
|---|--------|---------------|
| **[IV](../factors/04-research-before-you-build.md)** | **Research Before You Build** | Understand the problem space before generating a single line of code. |
| **[V](../factors/05-validate-externally.md)** | **Validate Externally** | The worker reports evidence; an independent checker writes the binding verdict. No agent grades its own work. |
| **[VI](../factors/06-lock-progress-forward.md)** | **Lock Progress Forward** | Once work passes validation, it ratchets forward and cannot regress. |
| **[IV](../factors/04-enforce-least-privilege.md)** | **Enforce Least Privilege** | An agent acts inside a least-privilege envelope it cannot widen -- not even on untrusted input. |
| **[V](../factors/05-research-before-you-build.md)** | **Research Before You Build** | Understand the problem space before generating a single line of code. |
| **[VI](../factors/06-isolate-workers.md)** | **Isolate Workers** | Each worker gets its own workspace, context, and zero shared mutable state. |

### Knowledge (VII--IX) -- Where Compounding Kicks In
### Select (VII--IX) -- Where Compounding Kicks In

Systematic extraction and injection of knowledge. This is where sessions start
getting measurably smarter over time.
Validate, lock, and extract -- selecting the work that holds. This is where sessions
start getting measurably smarter over time.

| # | Factor | One-Line Rule |
|---|--------|---------------|
| **[VII](../factors/07-extract-learnings.md)** | **Extract Learnings** | Every session produces two outputs: the work product and the lessons learned. |
| **[VIII](../factors/08-compound-knowledge.md)** | **Compound Knowledge** | Learnings flow back into future sessions automatically -- extract, gate, inject, measure, decay. |
| **[IX](../factors/09-measure-what-matters.md)** | **Measure What Matters** | Track fitness toward goals, not activity metrics. |
| **[VII](../factors/07-validate-externally.md)** | **Validate Externally** | The worker reports evidence; an independent checker writes the binding verdict. No agent grades its own work. |
| **[VIII](../factors/08-lock-progress-forward.md)** | **Lock Progress Forward** | Once work passes validation, it ratchets forward and cannot regress. |
| **[IX](../factors/09-extract-learnings.md)** | **Extract Learnings** | Every session produces two outputs: the work product and the lessons learned. |

> **Factor VIII is the hero.** It implements the knowledge flywheel -- the
> compounding loop that cannot be commoditized. Better models with amnesia still
> repeat your mistakes. Knowledge compounding is the one capability no amount of
> model improvement replaces.

### Scale (X--XII) -- The Factory Altitude
### Govern (X--XII) -- The Factory Altitude

The same factors at fleet scale. Working solo, you live them in miniature -- a
git worktree is isolation, your own judgment is supervision, your `learnings.md`
Expand All @@ -81,9 +76,14 @@ factors.

| # | Factor | One-Line Rule |
|---|--------|---------------|
| **[X](../factors/10-isolate-workers.md)** | **Isolate Workers** | Each worker gets its own workspace, context, and zero shared mutable state. |
| **[X](../factors/10-compound-knowledge.md)** | **Compound Knowledge** | Learnings flow back into future sessions automatically -- extract, gate, inject, measure, decay; dead ends become routing hints that prune the next agent's search. |
| **[XI](../factors/11-supervise-hierarchically.md)** | **Supervise Hierarchically** | Escalation flows up, never sideways -- one coordinator dispatches, workers execute. |
| **[XII](../factors/12-harvest-failures-as-wisdom.md)** | **Harvest Failures as Wisdom** | Turn dead ends into routing hints that prune the next agent's search. |
| **[XII](../factors/12-measure-outcomes.md)** | **Measure Outcomes** | Track fitness toward goals, not activity metrics. |

> **Factor X is the hero.** It implements the knowledge flywheel -- the
> compounding loop that cannot be commoditized. Better models with amnesia still
> repeat your mistakes. Knowledge compounding is the one capability no amount of
> model improvement replaces.

---

Expand All @@ -94,33 +94,34 @@ tier and keep the value.

```
Quickstart (5 min) --> learnings.md file, zero tooling
Foundation (I-III) --> Context discipline, git tracking, fresh sessions
Flow (IV-VI) --> Research, external validation, ratcheting
Knowledge (VII-IX) --> Extraction, compounding, measurement
Scale (X-XII) --> Multi-agent isolation, supervision, failure harvesting
Prepare (I-III) --> Context discipline, git tracking, fresh sessions
Bound (IV-VI) --> Least privilege, research, worker isolation
Select (VII-IX) --> External validation, ratcheting, extraction
Govern (X-XII) --> Knowledge compounding, supervision, measurement
```

| Transition | Trigger |
|------------|---------|
| Quickstart to Foundation | learnings.md gets unwieldy or context problems recur |
| Foundation to Flow | You keep re-explaining codebase patterns to new sessions |
| Flow to Knowledge | The same mistakes recur across sessions despite research |
| Knowledge to Scale | Multiple parallel agents cause conflicts |
| Quickstart to Prepare | learnings.md gets unwieldy or context problems recur |
| Prepare to Bound | You keep re-explaining codebase patterns to new sessions |
| Bound to Select | The same mistakes recur across sessions despite research |
| Select to Govern | Multiple parallel agents cause conflicts |

---

## Quick Reference by Pain Point

| Pain Point | Start With |
|------------|------------|
| Agent claims tests pass but code is broken | Factor V: Validate Externally |
| Agent claims tests pass but code is broken | Factor VII: Validate Externally |
| Context problems, instruction loss | Factor I: Context Is Everything |
| Scope creep, tangled implementations | Factor III: One Agent, One Job |
| Same mistakes repeated across sessions | Factor VIII: Compound Knowledge |
| No understanding before implementation | Factor IV: Research Before You Build |
| Cannot resume work across sessions | Factor VI: Lock Progress Forward |
| No visibility into what is working | Factor IX: Measure What Matters |
| Multi-agent workspace conflicts | Factor X: Isolate Workers |
| Same mistakes repeated across sessions | Factor X: Compound Knowledge |
| No understanding before implementation | Factor V: Research Before You Build |
| Agent over-reaches its permissions | Factor IV: Enforce Least Privilege |
| Cannot resume work across sessions | Factor VIII: Lock Progress Forward |
| No visibility into what is working | Factor XII: Measure Outcomes |
| Multi-agent workspace conflicts | Factor VI: Isolate Workers |

---

Expand Down
Loading
Loading