--- name: design description: "Writes the software design of a change before code is written, so that the review of the plugin laminar finds nothing on the code that follows. It writes 1 design model, which holds every public name at every scale and every named private part, with the decisions each boundary carries: 1 owner for each business decision, the depth of each choice from a forecast of change, the check of outside data at each entry, the failure line of each I/O execution and the tests of each entry. The shape check of the review judges the tree, a script checks the decisions, and writer agents then write the code, which the review checks. Use when the user asks to design a change or a feature before code, to plan the fixes of a run of the review skill of laminar, or to check a plan of Claude Code or a free-text idea such as a folder structure. It is not a review." --- # Design a change You design the code of a change before any code is written: its classes and methods, its folders, and the owner of each decision. You write 1 design model by `references/design-model.md`, `references/design-decisions.md` and `references/design-boundaries.md`. Scripts check it and render it as `design.md`, and the procedure ends at the plan: the model, `design.md`, the migration and `migration.workflow.js`. Writer agents then write the code from it, started by the session that called this skill or by section 5, and the review of the result shows whether the design reached its aim, which is a review with nothing to report on the change. You write no production code yourself and report no finding of your own. The book: "These questions check the planned structure the same way they check existing code, because the failures they target are cognitive rather than structural." (*How to Apply the Principles*, *How to Apply the Principles to New Code*) Contents: 1. The 2 modes · 2. The input · 3. The results folder · 4. The procedure · 5. Running the plan · 6. What this skill does not do · 7. The reference files ## 1. The 2 modes The skill runs in 1 of 2 modes. Say the mode in your first line. - The mode with a user, the default: you ask the user each question of the model (`AskUserQuestion`, in Claude Code), and the user approves `design.md` and the migration before the plan ends. - Autonomous mode, where the input asks for it, such as with `mode: autonomous`: you ask nothing, and each question takes the answer that its key `autonomous` states. A question whose `autonomous` is `default` takes its recommendation, for every kind of question, and `design.md` prints it as a decision taken by default; for a failure policy, the recommendation is the first choice of the failure line that fits the I/O execution (`references/designing.md`, section 10). Only a question about a change of an existing output that a program outside the application reads has its key `autonomous` set to `stop`, because such an output never changes without a user: the plan then ends with the outcome `question`, and the design and the question are the result. The form of a new output, such as the status code of a new failure or the fields of a new response, is no question: you decide it and write it in the model (`references/design-boundaries.md`, `entries`). A threshold or a boundary between applications stays open, and no writer writes code across it. The change forecaster answers depth. A finding of a review run or an item of a shape run stays unfixed only as `outside the change`, where git or the design check shows that the change did not touch its cause, as `project convention`, or as the decided list of the input decides it, because the calling session decided it. An item to consider that the tree does not answer takes `question to the author`: the finish command lists it under `considerations` of `outcome.json` and under *To consider* of `design.md`, and the plan stays `ready`, because an item to consider claims no defect, and autonomous mode passes it on, never in silence. The finish command with `--autonomous` reports every other reason of yours as the defect `reason-not-autonomous`. A defect of an existing field or member of a modified class is inside the change and takes no reason class: you fix it, and the migration carries the fix in a migration group of its own (`references/design-findings.md`, `existingDefects`); in the mode with a user it is a question whose recommendation is the fix. So autonomous mode can end in a question for the user, and it never passes a question in silence: `design.md` prints each answer that no user gave. ## 2. The input Read what the user gives (`$ARGUMENTS`, in Claude Code), and say in 1 short line what you got: - A described change: free text with ideas, such as a feature, a ticket or a folder structure, or a plan file, such as one written in the plan mode of Claude Code. Its scope is the folders that its words and its file names touch, which you find in the repository. - The run folder of a run of the skill `review` of the plugin laminar, at any scales. Read 3 files of it: `review.md` for the numbered items and the scope line, `review.sarif` for the abstraction, scale and places of each finding, and `review-evidence.md` for the evidence and the `Cause:` lines; the scripts also read its `prepare.json`. Its scope is the files the findings name and their folders. Every item of `review.md` at the application, module and class scales must be closed by the model, or left on purpose with 1 reason class of section 4, step 3. Each finding at the method and variable scales gets 1 finding step of the migration from the finish command, or 1 no-step line where the decided list decides it, where it is an item to consider, where a finished group of the plan before already fixed it, or where the model removes its abstraction (`references/design-checks.md`, section 5); so read it also as a sign of the cause. - `base: `: the base commit, the commit that the change starts from, such as the merge base of a branch, required with a run folder. Where a run folder comes with no base, ask the user for it; in autonomous mode the start command ends the plan. - `results: ` of an earlier plan: you start from its model, and the migration plans only what changed (section 3). - `decided: `: the findings of the run folder that the calling session already decided, each with 1 reason class of section 4, step 3, and `says`, in the form of `references/design-rounds.md`, section 2. You carry each one as it is and never decide it again. - `stop: `: the stops of the writers of the plan before, each with its group and the files the writer left uncommitted. Each stop is the first thing the new plan changes. - `mode: autonomous`: section 1. A run folder may come with a described change. The redesign of a folder or a module with no run folder and no described change comes in a later version: for it, ask the user for a described change, or for a run of the skill `review` on that folder first. ## 3. The results folder The results folder holds `design-model.json`, `design.md`, `migration.md`, `migration.workflow.js`, `base-commit.txt`, the base commit, `plan-commit.txt`, the head when the plan started, whose tree the scripts read as the current tree, `findings.json` for a run folder, the run folders of the shape runs under `shape-runs/`, 1 folder `plans//` per plan with its copies and its `outcome.json`, and, by section 5, the record of each round under `rounds//`. The user may name it as `results: `; else create a new temporary folder outside the repository. Name it in your first line. A results folder that already holds a model makes this plan a later plan: the start command carries that model onto the plan commit, so what the plan commit holds stands as written and each written method is marked `unchanged`, and the answers, the names, the stops and the reason classes of the shape runs stay. Remove `unchanged` from each method you change again and write its `body`. Never change the `group` of a class that an earlier plan held, because a stop and its left files name the group by its number. You write nothing into the repository; only the writers do. Read the repository itself, and never a review worktree under `.claude/worktrees/` of it, because a worktree holds another head of the same code, and code found there would steer the design. ## 4. The procedure The paths of the scripts are relative to the folder of this skill, and `` is the folder of the skill `review`, `../review` from here. 1. Run the start command, `node scripts/startPlan.mjs --results "" --repo ""`, with `--base ` from the input, `--run ""` for a run folder, `--stop ""` for the stops of the writers, and `--autonomous` in autonomous mode. It writes `base-commit.txt` and `plan-commit.txt`, numbers the plan, carries the model of an earlier plan and records each stop under `decisions.stops`. Where it prints a `second stop` line, ask the user a question about that abstraction, with the 2 stops as its fact; in autonomous mode it ends the plan itself. Where it exits 2 on a missing base, ask the user for the base. Read the input and find its scope. Read the project conventions as the skill `check-conventions` finds them: each `.md` file under `.claude/rules/conventions/` of the repository whose `paths:` match a folder of the scope, and each file there with no `paths:`. A project convention may set the zones and their zone order, the naming grammar, the folder layout and the test file suffixes. It overrides a rule marked narrower than the book, and never a format of this skill or a design direction of the book. 2. Read the current code of the scope, the private members included, by `references/designing.md`, section 1, and the reference files of the skill `code-style` that section 7 names. 3. For a run folder, ask of each finding whether it holds and what its cause is, on the code at the head and at the base of the reviewed range. A finding whose behavior the docs or the tests record as intended still holds. A finding stays unfixed only with 1 reason class of this closed set, never because you think it wrong and never because the repository repeats the form: `outside the change`, where the change did not touch its cause lines; `question to the author`, where the right shape rests on a fact the code does not show; `project convention`, where it rests on a rule marked narrower than the book and a conventions file of the project covers it; `exempt by the book`, where the book itself states the exemption, quoted with its chapter and section in italics, which also tells the maintainer of the plugin, because a finding against a sentence of the book is a defect of the review; and `fix apart`, where its fix reaches code outside the change in several modules. List every finding of 1 folder, at every scale, before you answer any of them, because a method finding often names the cause that a module finding only shows. Write 1 object of `decisions.findings` for each item at the application, module and class scales, with the part that closes it or its reason class (`references/design-findings.md`). Where the decided list decides an item, write its `reason`, its `says` and its `decidedBy`, `caller` where the list gives none, as they stand. Where a finding at the method or variable scale names a class that the model does not hold, add that class as `modified` with its whole listing and `addedForFindings`. 4. Pass 1, the tree. Write the shape half from the outside in, by `references/designing.md`, sections 2 to 8: the owners first, then the parts until every operation is a part, then the signatures, then the folders. Write `decisions.owners`. Start the change forecaster, the agent `design-forecaster` of the plugin (`laminar:design-forecaster`, in Claude Code), by `references/forecaster.md` once on this draft, and decide depth from its answer; where a later shape run adds owners, start it again on the added owners only. Write `decisions.exits` by `references/designing.md`, section 10, because the failure line of each I/O execution decides its return type. Then run the design check alone, `scripts/checkDesign.mjs` with the options of step 7, on this model and fix each defect it prints before the first shape check, other than the keys of pass 2, which it prints as missing: it costs no agent call and finds defects that would cost a shape run (`references/design-checks.md`, section 1). 5. Run the shape check on the tree. The prepare command reads the shape half of the design model and ignores the rest, so pass the model itself: `node "/scripts/runReview.mjs" prepare --run "/shape-runs/" --repo "" --shape "/design-model.json"`, where `` counts the shape runs from 1. Then run the judge workflow, the merge and the render of the skill `review`, as its steps 2 to 5 say. Run the merge and the render also on a run that keeps nothing, so its run folder holds `review.md` and `review.sarif`. After each shape run, report its measured cost, the judge workflow and the verify workflow together, as the host reports the use of each workflow; never report the cost plan of the prepare command as the cost, because it leaves out the verify workflow. Change the tree for each kept item and run the shape check again, until every kept item is closed by the tree or holds a reason class under `decisions.findings` (`references/design-findings.md`). Where the input states a ceiling, it counts shape runs, never dollars. The ceiling limits the shape runs, never the judging: where the tree changes after the last shape run the ceiling allows, run 1 shape check after the ceiling, a shape check of the changed items alone, each at its own scale (`--scales module|class|method --paths ` on the prepare command, with the scales of the changed folders, classes and methods), which counts as no shape run. Else leave each item that the change would close open, as `openAfterCeiling` with the intended change as its text (`references/design-findings.md`), keep the tree as the last shape run judged it, and `design.md` lists the item under `Open after the ceiling`. The parent folder of each folder that the change creates or moves stands in the shape half as a `modified` folder, because it gains a child. A class whose public members change gets a shape run also where it stays in its file. A method that coordinates 2 or more parts carries its `body` as the calls in order, and a method that does I/O carries its I/O line and its failure line, the same choice as its object under `exits`, so the judges read them before any code exists. Where the change creates, moves and removes no file and no folder and changes no public member, the shape check is not needed; say so with the reason. Where depth changes after the shape check passed, run the shape check again on the changed part only. In a host where the shape check cannot run, such as GitHub Copilot CLI, ask the detection questions of the 6 cognitive failures about each folder, class and signature yourself, and mark each answer as not checked by the review. 6. Pass 2, the decisions on the tree that passed: `decisions.conventions`, the `placement` of each owner, then `entries` with the `responses` of each entry, `tests` and `questions`, in the form of `references/design-decisions.md` and `references/design-boundaries.md`, by `references/designing.md`, sections 9, 11 and 13. Each question names the fact the code does not show, gives 2 or more options, each with its tree or its signatures, and a recommendation; an option that brings back the failure it was meant to close is no option. 7. Run the finish command on the whole model, `node scripts/finishModel.mjs --model "/design-model.json" --repo "" --results ""`, and add `--autonomous` in autonomous mode, `--review "/review.md"` where the input is a run folder, `--decided ""` with a decided list, `--classes ` in a later plan, the classes you changed in this plan, and `--shape-review "/shape-runs//review.md"` once per shape run. It writes `findings.json` from the run folder, runs in order the design check, `scripts/checkDesign.mjs`, the render, `scripts/renderDesign.mjs`, and the migration script, `scripts/planMigration.mjs`, passes each the options it takes, and stops at the first of them that prints a defect or fails, with the name of that script and its output; the 3 scripts may still run alone, with the options of their usage line. Where it passes, it writes `plans//` with `outcome.json` and prints the plan line last. Fix each defect it prints, and run it again. Recheck each recheck case it prints against the model; where the model shows that a case is wrong, write it as 1 object of `decisions.scriptCases` with its code, its display name and its text, so `design.md` shows it as a defect of the script (`references/design-findings.md`). 8. The finish command renders `design.md` into the results folder once the design check passes. Never write `design.md` by hand. 9. Ask the user the questions of the model, and write each answer under `answer`. Where an answer changes the shape half, run step 5 on the changed part. Then run steps 7 and 8 again, and show `design.md`. In autonomous mode, apply section 1 instead. 10. Set `group` on each class that the change creates, moves, renames, modifies or removes, and on no class of an `unchanged` file, by the boundary the classes share: an abstraction, a folder or a decision, and the narrower one where 2 fit, so the abstraction comes before its folder and the folder before the decision (`references/design-model.md`, section 3). Write the migration by running the finish command of step 7 again, which writes `/migration.md`; for the steps as JSON, run `scripts/planMigration.mjs` alone with an `--out` path that ends in `.json`. The migration script writes the steps per migration group in the order of the group numbers, and inside each group in 7 stages: folders, moves and renames, created classes, changed members, bodies, removals, and then tests (`references/design-checks.md`, section 5). A later plan is cut: it plans only the groups of the classes you changed, of the finding steps and of the stopped writers, and each group keeps its number (`references/design-checks.md`, section 5). Each finding at the method and variable scales gets 1 finding step, or 1 line under `## Findings with no step` where the decided list decides it, where it is an item to consider, where a finished group of the plan before already fixed it (`fixedBy` of `findings.json`), or where the model removes its abstraction. In the mode with a user, wait until the user approves `design.md` and the migration. 11. End the plan. Start no writer and run no review, because the session that called you does that, or section 5 does it. The last line of your report is the plan line of the last script you ran, `plan ready|question|stop `, which the finish command prints where it passes and the start command where it ends the plan. Never write the line by hand: a calling session reads `plans//outcome.json`, and the line names it. Report the measured cost of the shape runs. ## 5. Running the plan A plain session, which no other skill called, runs the plan by `references/design-rounds.md`: it starts the writer workflow (`Workflow({ name: "laminar:laminar-design-writers", args: { results: "", review: "/review.md" } })`, `review` only where the plan came from a run folder), which starts 1 writer per migration group, the agent `design-writer` of the plugin (`laminar:design-writer`, in Claude Code), by `references/writer.md`; in a host with no Workflow tool, it starts each writer in the order of the migration. It commits each finished group with its files and its commit message in the order of the group numbers. A finished group whose `build.result` is `failed` is not committed: the session writes it into the input `stop:` of the next call with the stop `build-failed`, at the `firstClass` of the group in `migration.workflow.js`, else at `migration group `, with the failing build command as `says` and the files of the group as `leftFiles`. 2 groups that share a file finish in 1 call of the writer workflow, so the files of a group can hold the lines of the other: a session that commits group by group calls the writer workflow once per group, in the order of the group numbers, with `groups: []`, and a call that writes the groups side by side suits a session that commits once. It then runs the skill `review` from the base commit to the head, and calls this skill again with the new run folder, the same results folder, the same `base:` and the stops of the writers. The round script compares the rounds and decides pass or stop there. A writer that stops leaves its files uncommitted, and the next plan takes its stop. ## 6. What this skill does not do - It is not a review. It reports no finding of its own, gives no finding a severity and does not rank the findings. - It is not a bug fix. A finding that names wrong behavior is fixed as a bug fix (the skill `code-style`, section 1), and only where the fix keeps every output that a user or another system reads. A change of such an output, such as a fail-fast fix that changes an exit code or the result of a gate, is a question to the user, never a silent fix (`references/designing.md`, section 13). - It takes no finding of another review skill as input, such as one that looks for bugs; name such a finding and leave it out. - It decides no fact that the code does not show, such as a threshold or where a boundary between applications runs; it asks the user, because "Which depth is right is a question about how the system will change, not something you can read from the code in front of you." (*The Encapsulation Principle*, *Depth Is a Design Decision*) ## 7. The reference files Each path is relative to the folder of this skill. The designer does not load the skill `code-style`; it reads these sections of its reference files, which hold the design directions of the shape: `../code-style/references/naming.md`, sections 1, 3, 8 and 9; `../code-style/references/classes.md`, sections 1, 2, 4, 5, 6, 8 and 9; `../code-style/references/modules.md`, sections 1, 2, 3, 4, 5, 8, 9 and 11; `../code-style/references/correctness.md`, sections 1, 2, 3, 8 and 10; and `../code-style/references/tests.md`, sections 3, 4, 5 and 12. Where the skill `code-style` is loaded in the session anyway, such as by a hook of the plugin before a first write, the designer still takes its rules from these sections alone. It reads the conventions file of each language of the scope, such as `../code-style/conventions/java.md`, only for the names of files and classes and for the forms of test names. - `references/design-model.md`: the form of the design model as a whole, the order of work, the shape half and its keys beside the shape model, the change marks, and which script reads which key; read before you write the model. - `references/design-checks.md`: what the design check reports, the zone order, the cycle check, and how the migration script orders its steps; read at steps 4, 7 and 10. - `references/design-decisions.md`: the keys `conventions`, `owners` with `forecast` and `questions` of `decisions`, and which script reads each; read at steps 4 and 6. - `references/design-findings.md`: the keys `findings`, `stops`, `existingDefects` and `scriptCases` of `decisions`, filled from the items of the review and the shape runs, the existing defects of a modified class, the recheck cases and the stops of the writer; read at steps 1, 3, 5 and 7. - `references/design-boundaries.md`: the keys `entries`, `exits` with the failure line, and `tests` of `decisions`, the decisions of each boundary, and which script reads each; read at steps 4 and 6. - `references/designing.md`: the rules of procedure of the designer; read at steps 2, 4 and 6. - `references/forecaster.md`: the inputs of the change forecaster and what the designer does with its answer; read at step 4. - `references/writer.md`: the inputs of the writer and what the designer does with a stop; read at step 1 and for section 5. - `references/design-rounds.md`: the decided list, the dispositions of a plan, and for section 5 the rounds, the round script with its counts, its comparison and its loop line; read at step 1 and for section 5. - `../review/shape-model.md`: the shape half, as the shape check reads it.