@iamdevlinph/codex-kit 1.0.24 → 1.1.0

package/README.md

@@ -44,7 +44,37 @@ TOML—not the routing policy—selects its model and reasoning effort. To avoid
 subagent startup overhead, the root may directly handle planning, conversation,
 read-only checks, documentation, bookkeeping, and clear changes spanning up to
 roughly three files. Automatic delegation is reserved for broad discovery,
-large multi-file implementation or debugging, and high-risk review.
+large multi-file implementation or debugging, high-risk review, and the
+structural review required for every completed feature.
+
+Every feature follows a mandatory semantic decomposition pass: implement and
+stabilize it, map each responsibility to its final file, extract independently
+understandable concerns, validate the decomposed implementation, and hand it to
+`code-reviewer`. Pages, routes, controllers, commands, and entrypoints contain
+composition and orchestration only. Web page files may contain framework exports,
+metadata, loading, guards, page-level state, minimal layout wrappers, and imported
+child composition, but not child components, substantial UI sections, or domain
+logic. Independently changeable UI concerns get descriptive feature-local files;
+hooks, schemas, data access, transformations, and domain logic move out of
+presentation when independently testable or when they obscure the primary
+responsibility. Avoid generic dumping grounds, keep components feature-local by
+default, and promote only proven shared/global primitives. Tiny inseparable
+helpers or markup may remain inline. Unrelated small fixes need no broad
+refactoring. Every completed feature receives automatic structural review; a
+concrete framework or tooling constraint must be named for any exception.
+
+User-facing work also begins with a UI/style preflight. Inspect the closest
+same-purpose shipped features—especially tables, filters, search, forms, dialogs,
+and page layouts—and reuse their components, tokens, layout, responsive
+behavior, interactions, states, and accessibility conventions. When repeated
+precedent exists without written guidance, record always-on conventions in
+`AGENTS.md` and feature-specific decisions or exceptions in `PLANS.md`. Ask the
+user whether to keep, update, or override before deliberate divergence,
+changing an established guideline, resolving conflicting precedents, or
+proceeding without a trustworthy analogue. Use browser or screenshot comparison
+when available; otherwise report it unavailable. The structural reviewer blocks
+unexplained divergence or needless duplication only when repository evidence
+supports the finding.
 
 ## Available subagents
 
@@ -52,7 +82,7 @@ large multi-file implementation or debugging, and high-risk review.
 | --- | --- | --- | --- |
 | `code-explorer` | Automatic | `gpt-5.6-terra`, medium | Read-only broad repository discovery, contract tracing, and multi-file searches |
 | `implementer` | Automatic | `gpt-5.6-luna`, high | Large behavior changes, non-obvious debugging, migrations, and substantial tests |
-| `code-reviewer` | Automatic | `gpt-5.6-sol`, high | Read-only review of security-sensitive, architectural, public-API, concurrency, migration, or difficult-to-validate changes |
+| `code-reviewer` | Automatic | `gpt-5.6-sol`, high | Structural review of every completed feature, plus read-only review of security-sensitive, architectural, public-API, concurrency, migration, or difficult-to-validate changes |
 | `quick-implementer` | Manual only | `gpt-5.6-luna`, medium | Small, mechanical, well-specified changes limited to one or two files |
 
 The root orchestrator is not a subagent. It owns planning, routing, integration,

package/assets/SUBAGENT_ROUTING.md

@@ -12,6 +12,39 @@ roughly three files when no broad discovery or architectural decision is needed.
 When a substantive route below matches, spawn that exact role before performing
 the role's work. The user does not need to request delegation.
 
+For user-facing work, the root or assigned worker performs a UI/style preflight
+before editing: inspect the closest same-purpose shipped features (especially
+tables, filters, search, forms, dialogs, and page layouts), identify their
+design-system primitives, tokens, spacing, typography, responsive behavior,
+interactions, states, and accessibility conventions, then reuse applicable
+components and patterns. If no written standard exists but trustworthy repeated
+precedent does, derive concise project-local guidance in `AGENTS.md` for
+always-on conventions and `PLANS.md` for feature-specific decisions or approved
+exceptions. Pause and ask the user whether to keep, update, or override before
+deliberate divergence, changing an established guideline, resolving conflicting
+precedents, or proceeding without a trustworthy analogue. If browser or
+screenshot tooling exists, compare the rendered feature with its analogue;
+otherwise report rendered comparison unavailable.
+
+Every new or materially changed feature follows this mandatory workflow:
+UI/style preflight; implement and stabilize; map each responsibility to its final file; extract
+independently understandable concerns; validate the decomposed implementation;
+then hand off to `code-reviewer`. Pages, routes, controllers, commands, and
+entrypoints contain composition and orchestration only. Web page files may keep
+framework exports, metadata, loading, guards, page-level state, minimal layout
+wrappers, and imported child composition, but not child components, substantial
+UI sections, or domain logic. Independently changeable UI concerns (tables,
+filters, forms, dialogs, and sections) receive descriptive feature-local files.
+Hooks, schemas, data access, transformations, and domain logic move out of
+presentation files when independently testable or when they obscure the primary
+responsibility. Avoid generic `utils`, `helpers`, or `components` dumping grounds;
+filenames identify owned behavior. Keep components feature-local by default;
+promote them only when reused across features or explicitly global primitives.
+Tiny private helpers or markup may remain inline only when inseparable from the
+file's single responsibility. Do not broaden unrelated small fixes. Every
+completed feature receives automatic structural review; a framework or tooling
+constraint is the only exception and must be named in the handoff.
+
 Select custom agents by exact name:
 
 - Broad repository discovery, contract tracing, or search across many files:
@@ -22,12 +55,14 @@ Select custom agents by exact name:
 - Independent review of security-sensitive, architectural, public-API,
   concurrency, migration, or otherwise difficult-to-validate changes:
   `code-reviewer`
+- Every completed feature, including small features, receives structural review:
+  `code-reviewer`
 
 For tasks with multiple phases, sequence only the roles that add value. For
 example, use `code-explorer` before implementation only when broad discovery is
-actually needed, and use `code-reviewer` after implementation only when the
-change meets its risk threshold. Avoid parallel write-heavy work by default and
-never assign overlapping files to multiple agents.
+actually needed. Use `code-reviewer` after every completed feature and for any
+other change meeting its risk threshold. Avoid parallel write-heavy work by
+default and never assign overlapping files to multiple agents.
 
 Multiple `implementer` instances may run concurrently only when a substantial
 task divides into genuinely independent slices. Give each instance exclusive

package/assets/TEMPLATE_AGENTS.md

@@ -104,6 +104,22 @@ conditional procedures into validated project skills.
   Do not assume tools from other projects.
 - Keep discovered stack-specific guidance in the project's
   `# Project-Specific Instructions`, not in this shared template.
+- For user-facing work, perform a UI/style preflight before editing: inspect the
+  closest same-purpose shipped features (especially tables, filters, search,
+  forms, dialogs, and page layouts) and identify their design-system primitives,
+  tokens, spacing, typography, responsive behavior, interactions, states, and
+  accessibility conventions. Reuse applicable components and patterns.
+- If no written standard exists but trustworthy repeated precedent does, derive
+  concise durable guidance in the project: always-on conventions belong in
+  `AGENTS.md`; feature-specific decisions and approved exceptions belong in
+  `PLANS.md`. During development, keep new UI aligned with that standard.
+- Pause and ask the user whether to keep, update, or override the standard
+  before deliberate visual divergence, changing an established guideline,
+  resolving conflicting precedents, or proceeding without a trustworthy
+  analogue. Include the evidence and affected pattern in the question.
+- If browser or screenshot tooling exists, compare the rendered feature with
+  the analogue across relevant responsive sizes and states. Otherwise, report
+  that rendered comparison was unavailable.
 
 ## Commands And Verification
 
@@ -129,12 +145,26 @@ conditional procedures into validated project skills.
   code under the feature's existing directory; when a feature contains multiple
   substantial UI pieces, place them in a `<feature>/components` subdirectory.
   Keep broadly reused code in the repository's established shared locations.
-- Keep route and page files focused on page-level composition, data loading, and
-  orchestration. Extract substantial self-contained UI sections and complex
-  page-specific logic into focused files colocated with the feature. Split large
-  or mixed-responsibility files by cohesive behavior so each file remains easy
-  to read, navigate, test, and review. Keep small one-use markup or logic inline;
-  do not create files or components solely to reduce line count.
+- Complete every new or materially changed feature through a semantic pass:
+  implement and stabilize it, map each responsibility to its final file, extract
+  independently understandable concerns, validate the decomposed implementation,
+  then hand it off to `code-reviewer`. Pages, routes, controllers, commands, and
+  entrypoints contain composition and orchestration only. Web page files may keep
+  framework exports, metadata, loading, guards, page-level state, minimal layout
+  wrappers, and imported child composition, but not child components, substantial
+  UI sections, or domain logic. Independently changeable UI concerns (tables,
+  filters, forms, dialogs, and sections) belong in descriptive feature-local
+  component files. Hooks, schemas, data access, transformations, and domain logic
+  move out of presentation files when independently testable or when they obscure
+  the component's primary responsibility. Avoid generic `utils`, `helpers`, or
+  `components` dumping grounds; filenames must identify owned behavior. Keep
+  components feature-local by default; promote them to shared/design-system
+  locations only when reused across features or explicitly global primitives.
+  Tiny private helpers or markup may remain inline only when inseparable from the
+  file's single responsibility. Do not broaden an unrelated small fix, but leave
+  any new or materially changed feature decomposed. Every completed feature gets
+  an automatic `code-reviewer` structure review; exceptions require a concrete
+  framework or tooling constraint identified in the handoff.
 - Use intent-revealing domain names. A reader should understand what a variable
   contains or what a helper guarantees at the call site without opening its
   implementation. Avoid vague transformation names such as `normalized`,
@@ -156,15 +186,15 @@ conditional procedures into validated project skills.
   platform suffixes such as `.ios.tsx`, `.android.tsx`, and `.native.tsx`.
 - Use `PascalCase` for components, context providers and consumers, type aliases,
   interfaces, and enums.
-- Use `snake_case` for ordinary variables, props, state values, and code-owned
-  object properties. Use `camelCase` for ordinary function names.
+- Use `camelCase` for functions, variables, props, state, and code-owned object
+  properties.
 - Name custom hooks as `useThing`, higher-order components as `withThing`, and
-  local event-handler functions as `handleThing`. Name code-owned callback props
-  in `snake_case` with an `on_` prefix, such as `on_submit`.
-- Prefix boolean props, state, and variables with `is_`, `has_`, or `should_`
+  local event-handler functions as `handleThing`. Name callback props with `on`,
+  such as `onSubmit`.
+- Prefix boolean props, state, and variables with `is`, `has`, or `should`
   when the prefix accurately describes their meaning.
 - Use `UPPER_SNAKE_CASE` for module-level constants and enum members. Keep
-  ordinary local `const` bindings in `snake_case`.
+  ordinary local `const` bindings in `camelCase`.
 
 ## Data And Validation
 

package/assets/agents/code-explorer.toml

@@ -14,7 +14,8 @@ You locate and distill the code relevant to a task so the orchestrator never has
 1. Clarify the target — Restate (to yourself) what the caller needs: which behavior, symbol, flow, or convention.
 2. Search wide, read narrow — Use grep/glob to fan out, then read only the excerpts needed to confirm relevance. Prefer reading specific line ranges over whole files.
 3. Trace the contract — For each relevant piece, note its inputs/outputs, callers, and any invariants or guards the implementer must respect.
-4. Report — Return the structured report below. Nothing else.
+4. UI/style preflight — For user-facing work, locate the closest same-purpose shipped UI and report its reusable components, design tokens, layout, responsive behavior, interaction/state, and accessibility conventions. Flag conflicting or missing precedents; do not invent a standard.
+5. Report — Return the structured report below. Nothing else.
 
 ## Report format (strict)
 - Conclusion — one paragraph answering the caller's question directly.
@@ -29,4 +30,5 @@ You locate and distill the code relevant to a task so the orchestrator never has
 - No raw dumps: never paste whole files or long grep output into your report — that defeats the purpose of delegating exploration.
 - If you find nothing, say so plainly and list where you looked.
 - Don't speculate about code you didn't read; mark inferences as inferences.
+- If no trustworthy analogue exists, say so so the root can ask the user whether to establish a new standard.
 """

package/assets/agents/code-reviewer.toml

@@ -16,6 +16,27 @@ review for correctness, regressions, security, reliability, missing tests, and
 architecture risks. Report only actionable findings, ordered P0 Critical through
 P3 Low, with precise file and line references.
 
+Every completed feature receives this structural review, regardless of file
+length. Enforce responsibility boundaries: return `REQUEST_CHANGES` when the
+final feature diff implements child UI inside a page or route file, mixes
+independently changeable responsibilities in one file, hides substantial logic
+inside presentation or entrypoint files, creates a generic file whose purpose is
+not clear from its name, puts feature-specific behavior in shared components, or
+duplicates genuinely shared behavior. Accept tiny private helpers/markup only
+when inseparable from a file's single responsibility. Allow an exception only
+for a concrete framework or tooling constraint explicitly identified in the
+handoff; otherwise end with `REQUEST_CHANGES` for violations.
+
+For user-facing changes, review consistency against the closest same-purpose
+shipped UI and applicable written `AGENTS.md`/`PLANS.md` guidance. Check reuse of
+existing components, tokens, layout, responsive behavior, interactions, states,
+and accessibility conventions. On repository evidence, return
+`REQUEST_CHANGES` for unexplained visual divergence or needless duplication of
+an applicable pattern. Do not demand a style choice unsupported by that
+evidence. Accept a deliberate exception only when the handoff records the
+user's keep/update/override decision; note unavailable rendered comparison
+without treating it as a failure.
+
 ## Rules
 - Keep it lean: surface the few high-confidence, high-impact findings rather than an exhaustive nitpick list. Rank by severity.
 - Finish within three minutes. At the deadline, stop and return the findings already supported by the diff.

package/assets/agents/implementer.toml

@@ -11,10 +11,12 @@ You write the actual code, its unit tests, and you run those tests to prove the
 
 ## Workflow
 1. Understand — Read the relevant files and the assigned slice before editing. Don't guess at contracts.
-2. Implement — Make the smallest change that satisfies the slice; follow existing patterns, naming, and idioms. Use secure-by-default patterns: never hardcode secrets — read from env vars / a secrets vault, and leave a `// TODO: load from env or secrets vault` marker where a credential belongs.
-3. Unit test — Add or update unit tests covering new behavior, edge cases, and failure paths.
-4. Validate — Run the unit tests (and linters/build if quick). Paste the actual result. If tests fail, fix and re-run — never report success on red.
-5. Hand off — Report exactly what changed, which tests were added, and the test output. State plainly if anything is unverified.
+2. UI/style preflight — Before editing user-facing code, inspect the closest same-purpose shipped features (especially tables, filters, search, forms, dialogs, and page layouts), then record the applicable components, tokens, layout, responsive behavior, interactions, states, and accessibility conventions. Reuse them. If no written standard exists but trustworthy repeated precedent does, derive concise always-on guidance in `AGENTS.md` and feature-specific decisions or exceptions in `PLANS.md`. Pause and ask the user whether to keep, update, or override before divergence, changing a guideline, resolving conflicts, or proceeding without a trustworthy analogue. Use browser or screenshot tooling for rendered comparison when available; otherwise report unavailable.
+3. Implement — Make the smallest change that satisfies the slice; follow the discovered UI and code patterns, naming, and idioms. Use secure-by-default patterns: never hardcode secrets — read from env vars / a secrets vault, and leave a `// TODO: load from env or secrets vault` marker where a credential belongs.
+4. Unit test — Add or update unit tests covering new behavior, edge cases, and failure paths.
+5. Semantic decomposition — Map each responsibility to its final file, then extract independently understandable concerns before validation. Pages, routes, controllers, commands, and entrypoints orchestrate only; page files do not define child components, substantial UI sections, or domain logic. Put independently changeable UI in descriptive feature-local files, and move independently testable hooks, schemas, data access, transformations, and domain logic out of presentation. Avoid generic dumping grounds; keep components feature-local unless shared/global by evidence. Tiny inseparable helpers or markup may remain inline. An unrelated small fix need not trigger broad refactoring. Name any concrete framework/tooling exception in the handoff.
+6. Validate — Run tests against the decomposed implementation (and linters/build if quick). Paste the actual result. If tests fail, fix and re-run — never report success on red.
+7. Hand off — Send every completed feature to `code-reviewer` for structural and UI consistency review. Report the responsibility map, extracted files, applicable precedent/standard, tests, rendered comparison or its unavailability, and output. State plainly if anything is unverified.
 
 ## Rules
 - No change is done until its tests are green and you've shown the output.

package/assets/agents/quick-implementer.toml

@@ -15,10 +15,12 @@ Proceed only when the requested change is well specified, localized to one or tw
 
 ## Workflow
 1. Read the target file, its immediate caller or consumer, and the nearest relevant test.
-2. Make the smallest in-scope edit. Preserve unrelated user changes.
-3. Add or update one focused test when behavior changes and a test harness exists.
-4. Run the narrowest relevant test, formatter, or config validation.
-5. Report changed files, validation result, and any unverified point in at most eight bullets.
+2. UI/style preflight — Before editing user-facing code, inspect the closest same-purpose shipped UI and reuse its components, tokens, layout, responsive behavior, interactions, states, and accessibility conventions. If no written standard exists but trustworthy repeated precedent does, record always-on guidance in `AGENTS.md` and feature-specific decisions or exceptions in `PLANS.md`. Pause and ask the user whether to keep, update, or override before divergence, changing a guideline, resolving conflicts, or proceeding without a trustworthy analogue. Use browser or screenshot comparison when available; otherwise report unavailable. Escalate visual-direction work beyond this role's scope to `implementer`.
+3. Make the smallest in-scope edit. Preserve unrelated user changes.
+4. Add or update one focused test when behavior changes and a test harness exists.
+5. Semantic decomposition — Map responsibilities to final files and extract independently understandable concerns before validation. Pages, routes, controllers, commands, and entrypoints orchestrate only; child UI, substantial sections, and domain logic belong in descriptive feature-local files. Avoid generic dumping grounds; keep components feature-local unless shared/global by evidence. Tiny inseparable helpers or markup may remain inline. Name any concrete framework/tooling exception.
+6. Validate the decomposed implementation with the narrowest relevant test, formatter, or config check.
+7. Hand off — Route every completed feature to `code-reviewer` for structural and UI consistency review. Report changed files, responsibility map, extracted files, applicable precedent/standard, rendered comparison or its unavailability, validation result, and any unverified point in at most eight bullets.
 
 ## Rules
 - Never broaden scope or refactor adjacent code.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iamdevlinph/codex-kit",
-	"version": "1.0.24",
+	"version": "1.1.0",
 	"description": "Portable Codex subagents and project AGENTS.md defaults.",
 	"type": "module",
 	"bin": {