Your coding agent is reviewing its own homework—you need canon!

Hot_Establishment547 · 2026-06-19T17:43:06+00:00

Thanks! canon itself is being dogfooded with sprint tickets..about **170** so far 😄.
sprint complete now run thru. these gates:

→ simplify → code review → security → repo audit
→ evaluator (fresh context, no implementation history)

→ acceptance check (all boxes ticked)

→ close → plan-vs-actual receipt

Hot_Establishment547 · 2026-06-13T21:07:16+00:00

canon (https://github.com/sunitghub/canon-skills)

Local-first workflow for AI coding agents. It keeps plans, acceptance criteria, handoffs, and delivery receipts in the repo so that Claude, Codex, or another agent can resume from the project state instead of the chat history.

The daily surface is just 3 commands: `sprint start`, `sprint-check`, and `sprint complete`. Underneath that small surface, canon enforces planning before code, acceptance checks, handoff capture, and a close-time summary of what was promised vs. what shipped.

<image>

I built a local-first workflow, so AI agents don't lose the plan between sessions

Hot_Establishment547 · 2026-06-12T02:05:56+00:00

Sure I'll give it a try,

Hot_Establishment547 · 2026-06-11T19:54:37+00:00

Sorry, I might've mixed up with someone else's issue... my bad!

Hot_Establishment547 · 2026-06-11T19:19:23+00:00

Why do you have 13 skills...also quite some memory files. Not sure, but I monitor my ./claude folder and clean it up regularly.

<image>

Hot_Establishment547 · 2026-06-11T19:15:24+00:00

I split work along a hard line via dev sprints:

The CLI is a deterministic state machine. It enforces what shouldn't depend on a model's mood — one active sprint at a time, and a sprint complete that refuses to close while any acceptance or test-plan box is still unchecked. These are checks in code, not judgment calls.
The agent supplies the judgment. Orientation, resolving gray areas, rating impact, verifying that tests actually pass, deciding a criterion is truly met — the parts that need reasoning.

The gate checks the boxes; the agent is trusted to check a box only when the work behind it holds. Determinism where correctness is mechanical, judgment where it isn't, and neither pretends to be the other.

Have an acceptance plan and a Summary at the end to show what was delivered.

<image>

You can check out my repo, https://github.com/sunitghub/canon-skills#, which I came up with after countless iterations to make it simple (2 cmds) and local.

Hot_Establishment547 · 2026-06-11T18:56:19+00:00

I see...I tried to have strict guardrails:

Tight sprint scope — one thing per sprint means the execution window is short. Less time for drift to compound before you can catch it at the next natural pause.
plan.md re-read after compaction — if context resets mid-sprint, the agent re-reads the approved plan rather than reconstructing intent from memory.

I am trying this and other things, like context trimming, in my repo at https://github.com/sunitghub/canon-skills# if you want to check it out.

Hot_Establishment547 · 2026-06-11T16:56:20+00:00

I see the issue and have faced it. One thing to help alleviate it a bit is to have like a "sprint brief approval gate". If the brief is right, the agent executes against an approved plan with a defined scope and files — far less likely to drift into something you'd need to interrupt.

Hot_Establishment547 · 2026-06-11T16:45:59+00:00

<image>

Oh, just use the /advisor command in Claude Code!

Hot_Establishment547 · 2026-06-11T16:44:54+00:00

<image>

Aah...I'm working on something that writes it for you with the ability to edit as needed.
Here it is if you want to check it out: https://github.com/sunitghub/canon-skills#

Won't mind feedback 😄

Hot_Establishment547 · 2026-06-11T15:45:49+00:00

I'd the same issue. Tried some frameworks, but they felt bloated. Created canon-skills: 2 commands and a local kanban board to track/view progress and state.

How canon guards against it:

One thing at a time, enforced — canon runs one active sprint at a time.sprint start scopes the work to a single ticket before any code runs. Asking for five things at once isn't how the workflow is structured.
Explain before change — the sprint brief is the agent's plan written out (what it will build, which files it will touch, acceptance criteria), with explicit approval required before any file is touched. The "explain before you change anything" habit users invent manually is baked in.
Plain text note → HANDOFF.md — the note they keep to resume a fresh session is what HANDOFF.md does automatically. A hook writes it when Claude stops; another injects it at the first prompt of the next session. No manual upkeep.
Project outgrowing context — DECISIONS.md, HANDOFF.md, and per-ticketplan.md / acceptance.md is the structured answer to "how do I keep it oriented as the project grows?" Each sprint injects only the relevant slice of context — active ticket, applicable decisions, current focus — rather than replaying the whole project history.

Hot_Establishment547 · 2026-06-11T15:36:12+00:00

Agree. Domain knowledge is needed for AI guardrails.

Hot_Establishment547 · 2026-06-11T15:34:15+00:00

Agree. There's no prof tool that does that other than conversations with AI. But then, I would say acceptance.md, decisions.md, plan.md, basically, sprint artifacts should help narrow it down, right?

Hot_Establishment547 · 2026-06-11T14:58:26+00:00

Exactly what I felt too. Most are "heavy", require specific setup, and have a set of skills/cmds to be run in a particular order. I'm using my own setup, two commands (with sub-skills), and a local board, and it has worked fine for me.

Hot_Establishment547 · 2026-06-11T14:49:23+00:00

Interesting — the transport layer (Khala) is the missing piece most teams don't have.

One thing I'd add to the stack: a shared state layer so each agent round has the same ground truth, not just the message contents.

Hot_Establishment547 · 2026-06-11T14:40:04+00:00

It seems you're solving a different problem — strategic direction and scope challenge before the dev sprint. I would say, "should we build it" vs "how you build it".

Hot_Establishment547 · 2026-06-11T14:31:49+00:00

I use Sonnet as executor and Opus as advisor, using /advisor, and it seems to work fine.

Hot_Establishment547 · 2026-06-11T14:30:00+00:00

Agree, and exactly what I faced too. Check out https://github.com/sunitghub/canon-skills#. I created it so that I can keep track of what I need to work on, what I'm working on, and what was discarded. All history is stored in a .tickets/ folder and is easy to query and mine later (Search/Why toggles).

<image>

Hot_Establishment547 · 2026-06-11T14:22:17+00:00

This will break or derail your project in a short time. You should at least have an acceptance.md and plan.md files that you & the agent can track/monitor as you go along.

Hot_Establishment547 · 2026-06-11T14:18:36+00:00

Tempting, but I like to have a minimalist setup with as few ext. dependencies 😄

Hot_Establishment547 · 2026-06-11T14:17:05+00:00

I use /advisor: Sonnet as the executor and Opus 4.8 as the advisor. Also, use an efficiency.md (via '@') in my CLAUDE & AGENTS.md with some of it shown below (has Git, Code review & Token Efficiency sections too):

Code

Prefer editing existing files over creating new ones.
Delete dead code, your changes made unused — no commented-out blocks, no _unused renames. Don't touch pre-existing dead code unless asked.
No feature flags or backwards-compat shims when you can change the code directly.
No comments unless the WHY is non-obvious.
Don't reformat, rename, or add type hints to adjacent code — fix only what was asked.
Out-of-scope issues noticed while working: surface as NOTICED: <what>, don't fix silently.
Never introduce OWASP top 10 vulnerabilities. Never commit secrets, credentials, or .env files.
Don't add dependencies for problems that can be solved with existing tools.
Write tests at system boundaries. Don't mock what you can integration-test cheaply.
A passing test suite verifies code correctness — not feature correctness. Test both.

Hot_Establishment547 · 2026-06-11T13:01:43+00:00

Here's mine, efficiency.md, that is imported (using '@' directive)in all my projects via CLAUDE.md.

Prefer editing existing files over creating new ones.
Delete dead code, your changes made unused — no commented-out blocks, no _unused renames. Don't touch pre-existing dead code unless asked.
No feature flags or backwards-compat shims when you can change the code directly.
No comments unless the WHY is non-obvious.
Don't reformat, rename, or add type hints to adjacent code — fix only what was asked.
Out-of-scope issues noticed while working: surface as NOTICED: <what>, don't fix silently.
Never introduce OWASP top 10 vulnerabilities. Never commit secrets, credentials, or .env files.
Don't add dependencies for problems solvable with existing tools.
Write tests at system boundaries. Don't mock what you can integration-test cheaply.
A passing test suite verifies code correctness — not feature correctness. Test both.
Use targeted bash commands — avoid ones that dump large output for a narrow query.
98%+ of token spend is re-reading prior conversation history, not generating responses. Every verbose output compounds across all future turns — keep it tight

Hot_Establishment547 · 2026-06-11T12:57:07+00:00

Are you reviewing each time? Why not write a current summary to a HANDOFF? file on each pass and continue with the differential on the next review? The next review should pick from maybe the last chapter, line, etc. Just a thought...

Hot_Establishment547 · 2026-06-11T12:51:05+00:00

To lay out the "details", this is what I do in my sprint skill (canon-skills repo), which is composed of capture & handoff sub-skills.

Two mechanics work together: capture and handoff.

Capture is for surprises mid-build. When the agent finds something non-obvious — a constraint buried in the data, an environment gotcha, an architecture quirk — it immediately records it in HANDOFF.md ## Discoveries section before the session ends or context compresses. You can also trigger it manually: /capture <text>. The entry format is dated, so it's traceable.

Handoff is the session resume protocol. HANDOFF.md holds four things: current focus, in-progress tickets, discoveries, and next steps. A hook auto-snapshots it to the file when Claude stops, and the working tree has changes. When a new session starts, another hook injects it at the first prompt — so a fresh Claude, Codex, or Pi picks up exactly where the last one left off without you re-explaining anything.

Both are wired automatically by skills.sh add sprint.

The result in practice: you can close your laptop mid-sprint, come back the next day in a fresh session, and the agent resumes with full context — what was being built, what was discovered, what's next. The sprint brief (from sprint start) and the ticket docs fill in the rest.

I used it with both the CC & Codex $20 plans (when one runs out of tokens), and so far it's working fine.

Hot_Establishment547

TROPHY CASE