Work with Design System Loop

npx ds-loop context .
npx ds-loop audit .

Then give your agent the outcome you need. It investigates the evidence and recommends a route. You don't need to classify your company or select a playbook.

Choose the closest task: start a system, improve one, transform it, or maintain it. If the problem is unclear, start below.

Agent commands

With the skill loaded, type /ds-loop:start or ask your agent to follow its command file. The colon is part of the command. The twelve command files route your task to procedures and roles; they aren't shell commands. Native slash-command discovery depends on your agent host. Directly reading a command file works when discovery isn't configured.

Roles and practice guides

The eight roles divide responsibilities within the same authorized task: auditor gathers measurements; consultant diagnoses and plans; architect maps structure; foundations compares scales and themes; components builds and checks contracts; migrator moves consumers; docs writes usable guidance; and governor retains owners and decisions. They're responsibilities your agent follows, not eight automatically launched agents.

The six practice guides support those roles: starting, maintaining, migrating, documenting, Storybook, and governing. Read the guide for your task before recommending a process. Keep each cited source beside the specific recommendation it supports; label the agent's own opinion.

If you do not know where to start

Tell the agent what brought you here. It should inspect existing evidence, ask only questions that affect the work, and explain a diagnosis before proposing changes. The plan should say what to change first, where it will be used, what must stay the same, who needs to decide anything, and how to check the result. It distinguishes what is known from what still needs investigation.

Read node_modules/ds-loop/skill/SKILL.md. Our teams keep building similar components and I do not know why. Investigate a representative example, explain likely causes and alternatives, and recommend what to do first. Do not begin a migration yet.

A precise task needs a shorter plan. Investigate further when the problem or the right response is unclear. An appropriate intervention may improve documentation or contribution practices instead of adding code.

Start a design system

Bring: a real screen or flow, product constraints, and any visual direction.

Your agent does: agree the product scope, inspect existing assets, and choose a compatible implementation base. For a setup request, it builds shared foundations, the primitives and patterns your workflows need, and a guide for using and changing them. A suitable existing library may provide the base.

You receive: editable sources connected to your product, working usage examples, customization and contribution instructions, and evidence of what was checked. A component gallery alone is not the finish line. A proposal or pilot request stays within that narrower scope.

Review: use the documented components in a new task, change a shared style, and extend a pattern. Check that the product and reference stay consistent. Automated checks and agent trials do not replace feedback from your developers.

Read node_modules/ds-loop/skill/SKILL.md. Set up a design system for this product so our developers can keep building it. Use our product notes and current workflows to recommend the scope, then implement it. Preserve working behavior and use an appropriate existing foundation where it fits. Make it clear how we use, customize and extend the result.

Improve a partial system

Bring: one inconsistency, the component, and the intended behavior.

Your agent does: trace existing patterns and consumers, compare behavior, and make an authorized repair or explain why the difference should stay.

You receive: a checked change or documented exception with the reason and affected files.

Review: the improvement and any behavior that must stay unchanged. A shared-token change may affect other components.

Read node_modules/ds-loop/skill/SKILL.md. Investigate why the primary button in src/settings/ differs from the shared Button. Check its states, themes, and existing decisions. If it is unintended drift, fix it within this screen and verify the result. If the difference serves a real need, keep it and record why. Do not change the shared scale or other screens without resolving that wider scope. Link the before/after evidence and the saved decision.

Transform an existing system

Use the nine-step transformation procedure when the goal spans diagnosis, foundation decisions, adoption and maintenance. It starts from existing commitments and ends with an evidence-backed completion record; it is an agent procedure, not a CLI command. The foundations procedure helps compare choices without assuming the current system should be replaced.

Establish theming areas and their override boundaries early. Before relying on Storybook or another preview, verify its CSS sources and order against the app. Label deliverables as observed, inferred, proposed or not checked. A scoped review can stop with a recommendation; a migration needs its own authorization.

Maintain an existing system

Bring: a diff or feature, component contracts, and previous decisions.

Your agent does: review against those commitments, run applicable checks, and separate regressions from existing issues.

You receive: a review with source locations, check results, and unresolved questions.

Review: whether the change honors the system across affected states and themes. Add edit feedback or CI after choosing a policy.

Read node_modules/ds-loop/skill/SKILL.md. Review my current diff against this project's design-system conventions and previous decisions. Trace the changed components across their affected states and themes. Report regressions separately from pre-existing issues, with source locations and checks that could not run. Make no code changes in this review. Link any decisions a later task needs to follow.

Three connected loops

The adoption loop sets the direction: understand the problem, investigate evidence and coverage, recommend a bounded intervention, verify the real flow, and retain the decision. Expand, revise or stop according to what the result demonstrates. Start, Improve, and Maintain change the action and deliverable; they are not scanner-derived maturity grades.

The audit loop supports a particular change: run context and an unfiltered audit, interpret the findings against intended behavior, change or preserve the code, rerun the audit, and review the real experience. Revise when evidence calls for it. A remaining finding can represent a justified exception or a checker limitation.

The optional guard loop runs during supported Claude Code edits: enable the hook, edit, audit the edited file, report high-severity findings and newly detected project extraction gaps, then review and revise if needed. A failed audit is reported as not checked. The hook runs after the edit and cannot block it. Lower-severity judgment limits still require an unfiltered audit; CI gating is separate.

The loops share your existing project conventions and the decisions you retain. Design System Loop does not maintain a central knowledge service or independently approve and ship changes.

Work with your agent

Replace example paths with your own. Give a concrete outcome and state what the agent may edit. The agent reads existing decisions, runs context and an unfiltered audit, and reports coverage gaps. It can carry out already authorized work. It asks when missing product intent or a wider change needs your decision.

Unread source needs another checker or manual inspection. Unfamiliar names need investigation of the actual naming contract. Configure the scanner only if it can represent that contract; changing configuration is not evidence that the product improved.

For visible changes, compare rendered before and after states. Rerun the unfiltered audit and checks that observe the affected behavior. Preserve the source revision, diff, and configuration with the evidence. Separate existing defects from regressions.

Review the handoff

The handoff states what was delivered, what was deliberately left unchanged, and what remains blocked. It links to changed files, actual checks and their limits, open questions, and relevant decisions. The record explains what was chosen, why, the affected scope, and when to reconsider. Use an existing issue, component document, or decision directory; a new registry is not required. Name where the next task finds it.

For an adoption pilot, ask a separate agent session to retrieve and apply that decision. Writing a record alone does not prove retrieval, suppress a finding, or create a checker.

See the complete synthetic example and its saved decision. Use the website preview to see the rendered before and after.