From 6b23c900bcce2c53d4d82652a0ac1fcea7fb43e0 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 24 Jun 2026 14:48:29 +0200 Subject: [PATCH 1/5] Refresh principles copy for AI-driven development --- app/src/components/sections/Principles.astro | 2 +- app/src/content/icons.ts | 139 ++++++++------- app/src/content/principles.ts | 26 +-- app/src/content/terms.ts | 177 +++++++++---------- app/src/lib/manifesto.ts | 1 + app/src/styles/sections/principles.css | 38 ++-- app/src/styles/sections/terminal.css | 12 +- 7 files changed, 202 insertions(+), 193 deletions(-) diff --git a/app/src/components/sections/Principles.astro b/app/src/components/sections/Principles.astro index 24a6f7f..0110f76 100644 --- a/app/src/components/sections/Principles.astro +++ b/app/src/components/sections/Principles.astro @@ -4,7 +4,7 @@ import PrincipleGrid from '~/components/principles/PrincipleGrid.astro';
-

12 commitments to produce high quality software, using AI.

+

12 commitments for durable AI-driven development.

without debt.', sub: 'Speed and quality are not in conflict. They are the same discipline, practiced twice.' }, - { n: "02", r: "2", hue: 50, lead: 'Planning is our first act of collaboration with AI.', sub: 'The quality of our plan determines the quality of our output. Everything downstream inherits it.' }, - { n: "03", r: "3", hue: 80, lead: 'We break complexity down until it can be delegated cleanly.', sub: 'Clarity of scope is clarity of output. Ambiguity compounds; decomposition dissolves it.' }, - { n: "04", r: "4", hue: 120, lead: 'Context is our primary asset.', sub: 'We invest in it, maintain it, and protect it from noise. A polluted context produces polluted code.' }, - { n: "05", r: "5", hue: 160, lead: 'We apply the same standards to AI-generated code as to any code we write by hand.', sub: 'There is no lower bar for generated work. Review, test, reject — the same rituals apply.' }, - { n: "06", r: "6", hue: 200, lead: 'We are the architects. Every line that ships is our line — regardless of what produced it.', sub: 'Authorship is not about the keystroke. It is about the judgment that sent the keystroke.' }, - { n: "07", r: "7", hue: 240, lead: 'We use AI to go further in what we already understand.', sub: 'We do not delegate what we have not mastered. Competence first; acceleration second.' }, - { n: "08", r: "8", hue: 270, lead: 'When a session loses coherence, we restart.', sub: 'A clean context is always cheaper than a compacted one. Fresh starts are not failures — they are hygiene.' }, - { n: "09", r: "9", hue: 300, lead: 'We choose a consistent methodology over a collection of tools.', sub: 'The method outlasts any model. Tools rotate; practice accrues.' }, - { n: "10", r: "10", hue: 330, lead: 'What one of us discovers, all of us adopt.', sub: 'The community is our compound learning machine. Hoarded technique decays; shared technique compounds.' }, - { n: "11", r: "11", hue: 10, lead: 'We recognize AI\'s limits as signals — not walls to push through, but invitations to decompose further.', sub: 'When the model stalls, the prompt is wrong. When the prompt is wrong, the scope is wrong.' }, - { n: "12", r: "12", hue: 28, lead: 'We do not stop learning because AI can code. We learn faster because it can.', sub: 'The leverage is real. What it multiplies is up to us.' }, + { n: "01", r: "1", hue: 28, lead: 'Ship in verified increments.', sub: 'Working software is the output of spec, plan, tests, review, and release.', proof: 'aidd-dev:00-sdlc' }, + { n: "02", r: "2", hue: 50, lead: 'Start from a clear spec.', sub: 'A story, PRD, or spec gives AI work a contract humans can inspect.', proof: 'aidd-pm:04-spec' }, + { n: "03", r: "3", hue: 80, lead: 'Plan before generation.', sub: 'The plan is the handoff between human judgment and agent execution.', proof: 'aidd-dev:01-plan' }, + { n: "04", r: "4", hue: 120, lead: 'Decompose until delegable.', sub: 'Small tasks survive async work, model changes, and team handoffs.', proof: 'aidd-dev:01-plan + 02-implement' }, + { n: "05", r: "5", hue: 160, lead: 'Craft context with the care we give code.', sub: 'Specs, markdown, rules, skills, and memory deserve the same quality bar as software.', proof: 'aidd-context:02-project-memory' }, + { n: "06", r: "6", hue: 200, lead: 'Capture learning for reuse.', sub: 'Each lesson becomes memory, a rule, a decision, or a skill others can use.', proof: 'aidd-context:05-learn' }, + { n: "07", r: "7", hue: 240, lead: 'Own every shipped change.', sub: 'AI may produce it; humans approve, merge, and maintain it.', proof: 'aidd-dev:05-review' }, + { n: "08", r: "8", hue: 270, lead: 'Do not delegate what you cannot evaluate.', sub: 'Use AI where you can judge tradeoffs, read the output, and prove behavior.', proof: 'aidd-dev:03-assert + 05-review' }, + { n: "09", r: "9", hue: 300, lead: 'Improve the system before forcing the model.', sub: 'When output degrades, clarify boundaries, names, tests, and context before asking harder.', proof: 'aidd-dev:07-refactor' }, + { n: "10", r: "10", hue: 330, lead: 'Rebuild context when coherence drops.', sub: 'Reset from memory, docs, rules, and the current plan instead of improvising.', proof: 'aidd-context:02-project-memory' }, + { n: "11", r: "11", hue: 10, lead: 'Treat AI failure as a signal.', sub: 'When the model stalls, inspect scope, context, assumptions, and tests before pushing harder.', proof: 'aidd-dev:08-debug + aidd-refine:02' }, + { n: "12", r: "12", hue: 28, lead: 'Make the practice transferable.', sub: 'A shared method lets different people produce the same quality of code across tools.', proof: 'aidd-vcs:01 + 02 + 03' }, ]; diff --git a/app/src/content/terms.ts b/app/src/content/terms.ts index 5bc06d5..eb50533 100644 --- a/app/src/content/terms.ts +++ b/app/src/content/terms.ts @@ -11,145 +11,136 @@ export interface Term { } export const TERMS: Term[] = [ - // 01 — Deliver fast (tests · lint · build · prod) { - title: "~/app · ship pipeline", + title: "demo · release ritual", lines: [ - { t: '$ ship "invoice-export"', d: 0 }, - { t: '› tests ✓ 482 passed 120ms', d: 400 }, - { t: '› lint ✓ clean 20ms', d: 700 }, - { t: '› types ✓ strict 30ms', d: 1000 }, - { t: '› build ✓ ready 900ms', d: 1300 }, - { t: '› deploy ✓ prod 1.2s', d: 1600 }, - { t: '[main 7f3a9c1] live · debt 0', d: 2000 }, + { t: '$ ship one-verified-slice', d: 0 }, + { t: 'contract ✓ written', d: 350 }, + { t: 'plan ✓ accepted', d: 650 }, + { t: 'change ✓ reviewed', d: 950 }, + { t: 'checks ✓ green', d: 1250 }, + { t: 'aidd-dev:00-sdlc keeps the loop honest.', d: 1550 }, ], }, - // 02 — Plan = collab humain ↔ AI, then handoff to autonomous AI { - title: "plan · two-phase handoff", + title: "demo · testable contract", lines: [ - { t: 'AI #1proposeshumandecidesAI #2autonomousphase 1 · reviewhandoffphase 2 · loop', d: 0 }, - { t: '✓ aligned · ✓ shipped · PR 421', d: 1400 }, + { t: '$ turn idea into contract', d: 0 }, + { t: '├── actor ✓ named', d: 400 }, + { t: '├── outcome ✓ observable', d: 750 }, + { t: '├── acceptance ✓ testable', d: 1100 }, + { t: '└── non-goals ✓ bounded', d: 1450 }, + { t: 'aidd-pm:04-spec before generation.', d: 1800 }, ], }, - // 03 — Decompose: 1 line on the surface vs what it really implies { - title: "decompose › the iceberg", + title: "demo · planned generation", lines: [ - { t: '$ task add "change user\'s group"', d: 0 }, - { t: 'surface: 1 line · looks simple', d: 500 }, - { t: '$ decompose', d: 1000 }, - { t: '├── api PATCH /users/:id/group', d: 1300 }, - { t: '├── db migration + audit log', d: 1500 }, - { t: '├── perms re-check on change', d: 1700 }, - { t: '├── ui form + confirm modal', d: 1900 }, - { t: '└── tests unit + e2e', d: 2100 }, - { t: '5 leaves · ready to delegate', d: 2500 }, + { t: '$ map path before-model-writes', d: 0 }, + { t: 'phase 1 data shape ✓', d: 400 }, + { t: 'phase 2 user journey ✓', d: 750 }, + { t: 'phase 3 failure states ✓', d: 1100 }, + { t: 'gate review criteria ✓', d: 1450 }, + { t: 'aidd-dev:01-plan writes judgment down.', d: 1800 }, ], }, - // 04 — Context = MCP + md + code + skills, not a prompt { - title: "context · system, not prompt", + title: "demo · delegable scope", lines: [ - { t: '$ context build', d: 0 }, - { t: '├── docs/*.md ✓ 12 files', d: 400 }, - { t: '├── src/**/*.ts ✓ 84 files', d: 700 }, - { t: '├── skills/aidd:* ✓ loaded', d: 1000 }, - { t: '└── mcp://serena ✓ live', d: 1300 }, - { t: '────────────────────────────', d: 1600 }, - { t: 'context = system · not a prompt.', d: 1900 }, + { t: '$ task split "change billing owner"', d: 0 }, + { t: '├── api PATCH /billing/owner', d: 450 }, + { t: '├── auth permission boundary', d: 800 }, + { t: '├── audit owner-change log', d: 1150 }, + { t: '└── tests unit + e2e', d: 1500 }, + { t: '4 leaves · each safe to delegate', d: 1850 }, ], }, - // 05 — Same standards: AI lines, marked, owned { - title: "src/group.ts · diff", + title: "demo · crafted context", lines: [ - { t: '/* @ai-generated · author: claude */', d: 0 }, - { t: '/* @reviewed @alex · @responsible @alex */', d: 400 }, - { t: '+ export function transferGroup(', d: 900 }, - { t: '+ uid: UserId, gid: GroupId', d: 1100 }, - { t: '+ ): Promise<Result> { ... }', d: 1300 }, - { t: '────────────────────────────', d: 1700 }, - { t: 'same review · same tests · same bar.', d: 2000 }, + { t: '$ write context-as-carefully-as-code', d: 0 }, + { t: '├── spec.md ✓ precise', d: 400 }, + { t: '├── rules.md ✓ usable', d: 750 }, + { t: '├── memory.md ✓ current', d: 1100 }, + { t: '└── skills/ ✓ reusable', d: 1450 }, + { t: 'aidd-context:02 keeps context engineered.', d: 1800 }, ], }, - // 06 — Architects: human draws the spine, AI fills the muscle { - title: "architecture · spine", + title: "demo · reusable learning", lines: [ - { t: 'human draws the spineapisvcdbAI fills the musclePOST /grpgeneratedservice.tsgeneratedmigrationgenerated', d: 0 }, - { t: 'spine: yours · muscle: theirs.', d: 1400 }, + { t: '$ capture what-worked', d: 0 }, + { t: 'decision token strategy ✓', d: 450 }, + { t: 'rule no hidden UI ✓', d: 850 }, + { t: 'skill release checklist ✓', d: 1250 }, + { t: 'team reuse ✓', d: 1650 }, + { t: 'aidd-context:05-learn makes it durable.', d: 2000 }, ], }, - // 07 — Go further: scope you can ship, before vs with AI { - title: "scope · ambition bar", + title: "demo · human ownership", lines: [ - { t: '$ scope --measure', d: 0 }, - { t: '', d: 300 }, - { t: 'solo: ███░░░░░░░░░░░ 3 weeks', d: 600 }, - { t: 'with AI: ██████████████ 3 days', d: 1100 }, - { t: '', d: 1400 }, - { t: 'multiplier: ×5 · bar moves up', d: 1700 }, - { t: 'ship what you couldn\'t ship before.', d: 2200 }, + { t: 'diff --generated src/billing.ts', d: 0 }, + { t: '+ transferOwner(account, user)', d: 450 }, + { t: '$ review as-maintainer', d: 900 }, + { t: 'human approval ✓', d: 1250 }, + { t: 'maintainer ✓ assigned', d: 1600 }, + { t: 'aidd-dev:05-review makes ownership explicit.', d: 1950 }, ], }, - // 08 — Restart: /compact, short example { - title: "session · /compact", + title: "demo · evaluation gate", lines: [ - { t: '› tokens █████████████████░ 94%', d: 0 }, - { t: '› coherence drifting · context noisy', d: 500 }, - { t: '$ /compact', d: 1100 }, - { t: '✓ compacted · intent kept', d: 1500 }, - { t: '$ continue plan.md', d: 1900 }, - { t: 'fresh context · same intent.', d: 2300 }, + { t: '$ evaluate before-delegate', d: 0 }, + { t: 'read output ✓', d: 400 }, + { t: 'tradeoffs ✓ understood', d: 750 }, + { t: 'tests ✓ passed', d: 1100 }, + { t: 'review ✓ accepted', d: 1450 }, + { t: 'assert + review prove judgment, not faith.', d: 1800 }, ], }, - // 09 — Method over tools: tools rotate at top, loop holds at bottom (agent center) { - title: "method · holds across tools", + title: "demo · system first", lines: [ - { t: 'tools: codexclaudecursoraidernext…', d: 0 }, - { t: 'models: opussonnethaikugptnext…', d: 300 }, - { t: 'agent↻planimplementtestreview', d: 700 }, - { t: '✓ tools change · loop holds.', d: 1900 }, + { t: '$ improve before-forcing-model', d: 0 }, + { t: '├── boundary ✓ clearer', d: 400 }, + { t: '├── naming ✓ simpler', d: 750 }, + { t: '├── tests ✓ closer', d: 1100 }, + { t: '└── prompt ✓ shorter', d: 1450 }, + { t: 'aidd-dev:07-refactor improves the shape.', d: 1800 }, ], }, - // 10 — Community: aidd-docs/ committed and shared { - title: "aidd-docs · committed", + title: "demo · clean restart", lines: [ - { t: '$ tree aidd-docs/', d: 0 }, - { t: '├── skills/ how we work', d: 400 }, - { t: '├── rules/ what holds', d: 700 }, - { t: '├── commands/ shared verbs', d: 1000 }, - { t: '├── templates/ starting points', d: 1300 }, - { t: '└── docs/ the why', d: 1600 }, - { t: '$ git push ✓ all peers in sync', d: 2000 }, - { t: 'one commit · whole community.', d: 2400 }, + { t: 'tokens ██████████████░ 91%', d: 0 }, + { t: 'coherence drifting', d: 450 }, + { t: '$ save plan.md ✓', d: 900 }, + { t: '$ load memory.md ✓', d: 1300 }, + { t: '$ restart clean ✓', d: 1600 }, + { t: 'same intent, fresh working set.', d: 1950 }, ], }, - // 11 — Limits as signals: pyramid of squares, same height, finer grain { - title: "signal · finer grain", + title: "demo · failure signal", lines: [ - { t: 'same volume · finer grain', d: 0 }, - { t: '1stalls4ok9clean16trivial', d: 400 }, - { t: 'stall = decompose further.', d: 1700 }, + { t: 'model stalled scope unclear', d: 0 }, + { t: '$ debug hypothesis', d: 450 }, + { t: '$ challenge plan.md', d: 900 }, + { t: 'assumption too broad', d: 1300 }, + { t: 'next step split scope', d: 1600 }, + { t: 'aidd-dev:08-debug turns failure into data.', d: 1950 }, ], }, - // 12 — Memory: every learning lands in memory.md { - title: "~/.aidd/memory.md", + title: "demo · transferable practice", lines: [ - { t: '$ tail -f memory.md', d: 0 }, - { t: '[apr 19] learn: oklch ≠ hsl hue ✓ noted', d: 400 }, - { t: '[apr 27] err: forgot null guard ✓ noted', d: 800 }, - { t: '[may 02] insight: planning > prompting ✓ noted', d: 1200 }, - { t: '[may 06] same trap? ─ no.', d: 1700 }, - { t: '────────────────────────────', d: 2100 }, - { t: 'memory compounds · same trap, never twice.', d: 2400 }, + { t: '$ capture team-practice', d: 0 }, + { t: 'decision review ritual ✓', d: 450 }, + { t: 'release v1.1 ✓', d: 900 }, + { t: 'code style shared by team ✓', d: 1350 }, + { t: 'tools rotate: codex · claude · next', d: 1750 }, + { t: 'aidd-vcs leaves a shared trail.', d: 2100 }, ], }, ]; diff --git a/app/src/lib/manifesto.ts b/app/src/lib/manifesto.ts index 2cd5888..e99e219 100644 --- a/app/src/lib/manifesto.ts +++ b/app/src/lib/manifesto.ts @@ -79,6 +79,7 @@ export function getManifestoJson() { number: principle.n, statement: stripHtml(principle.lead), summary: principle.sub, + frameworkTrace: principle.proof, })), }; } diff --git a/app/src/styles/sections/principles.css b/app/src/styles/sections/principles.css index bce1492..b54159a 100644 --- a/app/src/styles/sections/principles.css +++ b/app/src/styles/sections/principles.css @@ -1,5 +1,14 @@ /* ============ PRINCIPLES — twelve commitments, citable reference grid ============ */ .principles{ padding: 0 0 clamp(16px, 2.5vh, 28px); } +.principles .chapter-open{ + padding: clamp(48px, 7vh, 76px) 0 clamp(24px, 4vh, 40px); +} +.principles .chapter-body h2{ + max-width: 780px; + font-size: clamp(28px, 4vw, 52px); + line-height: 1.02; + margin-bottom: 0; +} /* ---- List: one commitment per full-width row, stacked vertically ---- */ .p-grid{ @@ -14,12 +23,11 @@ --row-inset: clamp(18px, 2.2vw, 28px); position: relative; display: grid; - grid-template-columns: clamp(48px, 5vw, 64px) minmax(0, 1fr) minmax(280px, 420px); - gap: clamp(18px, 2vw, 28px); + grid-template-columns: clamp(44px, 4.6vw, 58px) minmax(320px, 1fr) minmax(280px, 380px); + gap: clamp(18px, 1.9vw, 28px); align-items: start; min-width: 0; - /* Generous breathing room — rows were too cramped. */ - padding: clamp(40px, 6.5vh, 78px) var(--row-inset); + padding: clamp(26px, 4.3vh, 46px) var(--row-inset); scroll-margin-top: clamp(20px, 8vh, 80px); border-bottom: 1px solid var(--rule); background: var(--paper); @@ -76,7 +84,7 @@ font-family: var(--display); font-style: normal; font-weight: 700; - font-size: clamp(38px, 4vw, 56px); + font-size: clamp(32px, 3.4vw, 46px); line-height: 1; color: var(--ink); letter-spacing: -0.03em; @@ -102,11 +110,11 @@ position: absolute; /* Offset from the number's own height (line-box = font-size) + a small gap, rather than 100% — the number's line-box can render taller than expected. */ - top: calc(clamp(38px, 4vw, 56px) + 18px); + top: calc(clamp(32px, 3.4vw, 46px) + 16px); left: 0; - width: clamp(50px, 4.8vw, 62px); - height: clamp(50px, 4.8vw, 62px); - padding: clamp(13px, 1.3vw, 16px); + width: clamp(44px, 4.3vw, 54px); + height: clamp(44px, 4.3vw, 54px); + padding: clamp(11px, 1.15vw, 14px); /* Single accent by default; --p-color is only set when the "rainbow" tweak is on (see ClientApp). No per-principle gradient otherwise. */ --plate-mark: var(--p-color, var(--accent)); @@ -121,11 +129,11 @@ font-family: var(--display); font-style: normal; font-weight: 600; - font-size: clamp(20px, 1.9vw, 26px); - line-height: 1.25; + font-size: clamp(18px, 1.55vw, 22px); + line-height: 1.22; letter-spacing: -0.015em; color: var(--ink); - margin-bottom: 14px; + margin-bottom: 10px; text-wrap: pretty; } @@ -161,10 +169,10 @@ .p-sub{ font-family: var(--sans); font-style: normal; - font-size: 14.5px; - line-height: 1.6; + font-size: 13.5px; + line-height: 1.55; color: var(--ink-2); - max-width: 48ch; + max-width: 44ch; } /* ---- Tablet: drop the side code panel under the statement ---- */ diff --git a/app/src/styles/sections/terminal.css b/app/src/styles/sections/terminal.css index 596511c..9a6998e 100644 --- a/app/src/styles/sections/terminal.css +++ b/app/src/styles/sections/terminal.css @@ -7,14 +7,14 @@ .term{ grid-column: 1 / -1; - margin-top: clamp(18px, 2.5vh, 26px); + margin-top: clamp(14px, 2vh, 20px); border: none; border-radius: var(--radius-card); background: var(--ink); /* navy — the "dark" inverse */ color: oklch(0.88 0.012 275); /* ice-ish on navy */ font-family: var(--mono); - font-size: 11.5px; - line-height: 1.65; + font-size: 10.8px; + line-height: 1.58; overflow: hidden; position: relative; min-width: 0; @@ -50,11 +50,11 @@ .term .tbody-title{ display: block; font-family: var(--mono); - font-size: 10px; + font-size: 9px; letter-spacing: .16em; text-transform: uppercase; color: oklch(0.48 0.018 272); - padding: clamp(14px, 1.8vw, 18px) clamp(18px, 2.2vw, 24px) 0; + padding: clamp(12px, 1.5vw, 15px) clamp(16px, 2vw, 20px) 0; position: relative; z-index: 2; } @@ -66,7 +66,7 @@ /* Body — the code lines. No forced min-height: the panel hugs its content (lines reserve their space at opacity 0, so there is no layout shift). */ .term .body{ - padding: clamp(10px, 1.4vw, 14px) clamp(18px, 2.2vw, 24px) clamp(16px, 2vw, 20px); + padding: clamp(8px, 1.2vw, 12px) clamp(16px, 2vw, 20px) clamp(14px, 1.8vw, 18px); position: relative; z-index: 2; overflow-x: auto; From 3ac16ad8d6b13d67d26a6422a25b2aabdba6fc7b Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 24 Jun 2026 20:54:49 +0200 Subject: [PATCH 2/5] Replace terminal demos with principle visuals --- app/src/components/ClientApp.astro | 3 +- app/src/components/layout/Page.astro | 2 +- .../components/principles/PrincipleCard.astro | 8 +- .../components/principles/PrincipleDemo.astro | 39 ++ .../components/principles/PrincipleGrid.astro | 3 +- .../components/terminal/TerminalAnim.astro | 13 - app/src/content/icons.ts | 4 +- app/src/content/principles.ts | 8 +- app/src/content/terms.ts | 146 ------ app/src/lib/observers.ts | 25 - app/src/styles/sections/principle-demos.css | 429 ++++++++++++++++++ app/src/styles/sections/principles.css | 23 +- app/src/styles/sections/terminal.css | 242 ---------- 13 files changed, 495 insertions(+), 450 deletions(-) create mode 100644 app/src/components/principles/PrincipleDemo.astro delete mode 100644 app/src/components/terminal/TerminalAnim.astro delete mode 100644 app/src/content/terms.ts create mode 100644 app/src/styles/sections/principle-demos.css delete mode 100644 app/src/styles/sections/terminal.css diff --git a/app/src/components/ClientApp.astro b/app/src/components/ClientApp.astro index 1ae0f6b..cb14243 100644 --- a/app/src/components/ClientApp.astro +++ b/app/src/components/ClientApp.astro @@ -3,10 +3,9 @@ // EDIT MODE sentinel preserved verbatim (do not rename markers). ---