onedot-devkit — Vision and User Flows

This page defines the target experience and supported workflows. Maintainers use it to decide product scope; developers are routed through the flows without memorizing them.

Goal

Deliver maximum AI leverage with minimum onboarding. Leverage means fewer loops, less elapsed time, fewer tokens and errors at equal or better output quality, measured as Results-decide requires. Onboarding means install → sync → devkit init → /index yields ready context without reading the manual. A developer installs once and works normally while quality, security, and token efficiency arrive by default; the setup routes, reminds, and checks.

The 6 Pillars

#	Pillar	Meaning
1	Autopilot	Benefits work without knowing every skill, rule, or hook.
2	Security	Secrets, sandbox boundaries, destructive actions, and push gates are safe by default.
3	Quality by default	Reuse, verification, tests, and review are part of the routed workflow.
4	Self-skepticism	Load-bearing decisions receive an independent counter-check.
5	Token efficiency	Deterministic tools and scoped context do work that does not need an LLM.
6	Stack fit	The setup serves Laravel, Nuxt, Shopify Liquid, Shopware/Twig, and Python. A stack is added when representative work needs its conventions and verification; a stack leaves when no maintained flow uses it.

User Flows

Every flow ends in executable evidence, not a prose promise.

Flow	When and route
0 — Onboarding	Install devkit → devkit sync → devkit init and /index inside the project → .agents/context/ is ready. Later sessions check for updates automatically. Evidence: generated .agents/context/ plus a green context-drift check.
1 — Reversible daily work	If rollback is free and deterministic verification exists: describe the outcome → work inline → targeted /test → /review → /commit. Deliberately no spec overhead; file count affects effort, not routing.
2 — Contract work	If rollback is expensive or deterministic verification cannot exist yet: /spec → /spec-work → /commit → pull request. /spec normally uses the compact contract; it uses the full route for high risk, irreversible migration, a security or public-contract boundary, a cross-repository release, at least three independent subsystems, novel architecture, or a new mutating step in an ordered pipeline. /review --spec is an optional manual re-review. Gate chain: spec validation → step verification → tests and quality checks → independent review.
3 — Initiative	For at least three specs, an external provider, or a transformation across system boundaries: optionally /brainstorm → define the next smallest slice with /spec → /spec-work → only then plan the next slice. Use /delegate for an independent view on a load-bearing provider or slice decision. /wave schedules approved specs behind preflight, cost, and acceptance gates; it does not choose the slice.
4 — Knowledge and context	Gotcha, convention, or decision → /capture → .agents/context/. Past questions use memory recall. Check drift with devkit context-drift-check. Evidence: the updated context file plus a green drift check.
5 — Maintenance	SessionStart applies a staged update and fetches the next in the background. devkit sync runs the immediate manual path; devkit doctor diagnoses the installation; devkit rollback returns to an earlier version. Evidence: green devkit doctor output, or a verified rollback to the named version.

Product Decision Principles

A capability belongs when it supports at least one flow and one pillar without regressing autopilot or token efficiency, shown with the same baseline and instrument Results-decide requires. A required special ritual misses the target; safety or quality that depends only on model prose should become an executable check.

Principle	Decision rule
Standards first	Prefer native runtime behavior. Add only routing, shared policy, or verification the host lacks instead of hiding a built-in behind another layer.
Reference first	Treat maintained external projects as candidates, not authorities. Compare established approaches and test promising ones on representative work; familiarity is not evidence.
Results decide	Measure fewer loops, less elapsed time, fewer tokens and errors, and better output. Package size alone is not a verdict: a larger dependency may help, while a tiny always-on rule may cost more than it returns. Each claim names its baseline, its instrument (devkit-usage telemetry, devkit-retro cost, or a pinned benchmark task), and its threshold before adoption.

Adoption and Ownership

Adopt a maintained capability when it performs better; building a substitute is the exception. A behavior collision is a migration cost to assess, not an automatic rejection.

• Evidence: Treat README claims and upstream benchmarks as hypotheses. Trial real payloads and representative tasks; evaluate library, proxy, service, or other surfaces separately.
• Reversibility: Pin the version, inspect install-time side effects, capture changeable configuration, and verify rollback rather than trusting a backup message. State missing measurements without invented precision.
• Simplification: Name what leaves. An overlapping route is accretion; if nothing leaves, keep that cost visible.

Three ownership forms fit:

1. A version-pinned external tool with explicit upgrade review.
2. External ideas adapted into owned text and behavior, with attribution.
3. A verbatim snapshot pinned to an upstream commit and treated as reference data until adapted.

Floating foreign behavioral instructions without a version boundary or local ownership do not fit. External material remains untrusted until reviewed, pinned, and adapted because it can steer every answer without an update gate.

The policy is refutable. If representative evaluations show a pinned external canon gives durable, better quality at lower lifecycle cost, reference-first requires adoption; keeping a weaker local version because it is ours violates the goal.

Architecture Boundary

Updater, signature verification, atomic activation, collision protection, and rollback form one supply-chain contract. External ideas may improve it, but direct templates need equivalent ownership and verification.

Rules, skills, and agents can be adopted more selectively because each is measured against a flow and token budget. Both layers still come from one source payload and project into supported runtimes; adapters must not become separate policy canons.

Replace repeated prose duties with deterministic mechanics wherever behavior is observable. This advances autopilot, quality, and token efficiency while prose retains intent and tradeoffs.

Self-Skepticism in the Product

• /challenge applies adversarial frames to a decision.
• /spec expands challenge and authoring review for high-risk or novel architecture work.
• /spec-work binds independent review evidence to the scoped change it reviewed.
• Quality and debugging rules require a counter-hypothesis and stop condition for load-bearing investigations.
• /delegate provides a cross-model second opinion when an independent model is useful.