@iamdevlinph/codex-kit 1.0.25 → 1.1.1

package/README.md

@@ -1,258 +1,162 @@
 # `@iamdevlinph/codex-kit`
 
-Portable Codex setup for new devices and multiple projects. It provides:
+Portable Codex subagents, automatic task routing, and reusable project guidance.
 
-- three automatically routed roles plus a manual quick implementer
-- automatic global role routing
-- a reusable, stack-neutral `AGENTS.md` template
-- a package-owned `codex-kit-reconcile-agents` skill for semantic reconciliation
-- safe commands for global setup, project synchronization, and reconciliation
+- Routes work automatically while keeping small tasks with the root agent.
+- Includes four subagents for exploration, implementation, review, and quick edits.
+- Provides a stack-neutral `AGENTS.md` starting point.
+- Reconciles template updates semantically instead of replacing project guidance.
+- Preserves user-owned configuration and modified managed files.
+- Runs as a dependency-free Node.js CLI.
 
-The package contains no credentials. Global installation configures the Codex
-root orchestrator to `gpt-5.6-sol` with low normal reasoning and high Plan-mode
-reasoning. Use the separate configuration command to override these defaults.
+## Quick start
 
-## Install on a device
+1. Install the CLI and global Codex assets:
 
-No npm or GitHub login is required. For regular use, install the CLI globally:
+   ```sh
+   pnpm add --global @iamdevlinph/codex-kit@latest
+   codex-kit global install
+   ```
 
-```sh
-pnpm add --global @iamdevlinph/codex-kit@latest
-codex-kit global install
-```
-
-Start a new Codex task or restart the client after installation. Codex may ask
-you to review and trust the new command hooks once; approve them after confirming
-that they run the installed `${CODEX_HOME:-~/.codex}/codex-kit/routing-hook.js`.
-
-`npm install --global @iamdevlinph/codex-kit@latest` works as an alternative.
-For one-off use without a global installation, prefix a command with
-`pnpm dlx @iamdevlinph/codex-kit@latest`.
-
-`global install` copies reusable agents and the
-`skills/codex-kit-reconcile-agents` skill to `${CODEX_HOME:-~/.codex}`, maintains
-the package routing section in global `AGENTS.md`, and adds package-owned
-handlers to `hooks.json` without replacing existing hooks. `global list` shows
-the reconciliation skill's ownership status. Install and uninstall preserve
-modified or user-owned skill files using the same backup/restore semantics as
-other package files.
-
-The Sol root plans, routes, coordinates, and validates. On every prompt, the
-routing hook supplies the current `SUBAGENT_ROUTING.md`; the root classifies the
-task and delegates substantive work to the exact matching role. The role's agent
-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.
-
-## Available subagents
-
-| Subagent | Routing | Model and effort | Used for |
-| --- | --- | --- | --- |
-| `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 |
-| `quick-implementer` | Manual only | `gpt-5.6-luna`, medium | Small, mechanical, well-specified changes limited to one or two files |
+2. Initialize a project from its root:
 
-The root orchestrator is not a subagent. It owns planning, routing, integration,
-and final validation.
+   ```sh
+   codex-kit project init
+   ```
 
-For a substantial task that splits into genuinely independent slices, the root
-may run multiple `implementer` instances concurrently. Each receives exclusive
-file or module ownership and separate validation scope. Work that shares types,
-schemas, configuration, generated artifacts, migrations, lockfiles, or dependency
-ordering stays with one implementer or runs sequentially; multiple files alone
-do not justify duplicate agents.
-
-`quick-implementer` remains installed for explicit manual delegation but is not
-selected by the default automatic route. The root reuses delegated test evidence
-and normally performs only lightweight integration checks.
-
-`global install` sets these defaults while preserving unrelated settings;
-`global configure` can override them:
-
-```toml
-model = "gpt-5.6-sol"
-model_reasoning_effort = "low"
-plan_mode_reasoning_effort = "high"
-```
-
-This balances ordinary orchestration and direct small changes while retaining
-high reasoning in Plan Mode. Override either effort independently when needed:
-
-```sh
-codex-kit global configure \
-  --reasoning-effort low \
-  --plan-reasoning-effort high
-```
-
-Delegation is time-bounded. The root waits once for up to 60 seconds, requests
-one progress update, and then enforces a three-minute read/review/manual-quick
-deadline or five-minute implementation deadline. Validation commands that make
-no progress for two minutes are stopped unless the repository documents a
-longer normal runtime. Root and worker never run the same validation
-concurrently.
-
-Before changing these keys, codex-kit creates a timestamped `config.toml`
-backup and records their previous values. `global uninstall` restores those
-values without replacing unrelated configuration changed afterward.
-
-Use a different Codex home when needed:
-
-```sh
-pnpm dlx @iamdevlinph/codex-kit@latest global install \
-  --codex-home /path/to/.codex
-pnpm dlx @iamdevlinph/codex-kit@latest global configure \
-  --codex-home /path/to/.codex
-```
-
-Inspect the installed setup:
-
-```sh
-pnpm dlx @iamdevlinph/codex-kit@latest global list
-```
+Restart Codex after global installation. Codex may ask you to trust the installed
+hook at `${CODEX_HOME:-~/.codex}/codex-kit/routing-hook.js`.
 
-The summary shows the Codex home, orchestrator, normal and Plan-mode reasoning
-effort, routing-file and routing-hook status, reconciliation-skill status, and
-installed custom agents without dumping unrelated configuration.
+`npm install --global @iamdevlinph/codex-kit@latest` is also supported. For
+one-off use, prefix commands with `pnpm dlx @iamdevlinph/codex-kit@latest`.
 
-Uninstall package-managed global files:
+## Included subagents
 
-```sh
-pnpm dlx @iamdevlinph/codex-kit@latest global uninstall
-```
+| Subagent | Routing | Model and effort | Purpose |
+| --- | --- | --- | --- |
+| `code-explorer` | Automatic | `gpt-5.6-terra`, medium | Broad read-only discovery and contract tracing |
+| `implementer` | Automatic | `gpt-5.6-luna`, high | Large changes, debugging, migrations, and substantial tests |
+| `code-reviewer` | Automatic | `gpt-5.6-sol`, high | Feature structure and high-risk review |
+| `quick-implementer` | Manual | `gpt-5.6-luna`, medium | Small mechanical changes in one or two files |
 
-Uninstall removes only codex-kit's handlers from `hooks.json` and preserves other
-hooks. Modified managed files are preserved unless `--force` is supplied.
+The root orchestrator plans, routes, integrates, and validates. It handles clear
+small changes directly and delegates broader discovery, implementation, or review
+according to the installed `SUBAGENT_ROUTING.md` policy.
 
 ## Commands
 
 | Action | Command |
 | --- | --- |
-| Show command help | `codex-kit -h` or `codex-kit --help` |
-| Print the installed version | `codex-kit -v` or `codex-kit --version` |
-| Install global agents and routing | `codex-kit global install` |
-| Configure the orchestrator | `codex-kit global configure` |
-| Inspect global configuration | `codex-kit global list` |
+| Show help | `codex-kit -h` or `codex-kit --help` |
+| Print version | `codex-kit -v` or `codex-kit --version` |
+| Install or update global assets | `codex-kit global install` |
+| Configure model defaults | `codex-kit global configure` |
+| Inspect global setup | `codex-kit global list` |
 | Remove package-managed global files | `codex-kit global uninstall` |
 | Initialize project guidance | `codex-kit project init` |
-| Refresh the project template reference | `codex-kit project sync` |
-| Check template reconciliation | `codex-kit project status` |
+| Refresh the project template | `codex-kit project sync` |
+| Check reconciliation status | `codex-kit project status` |
 | Record completed reconciliation | `codex-kit project mark-applied` |
 | Check for a package update | `codex-kit version check` |
 
-## Apply to a project
+Use `codex-kit --help` for exhaustive command details.
 
-### First-time setup
+## Device setup
 
-For a new blank project, scaffold its initial stack first. Then initialize
-codex-kit once from the project root:
+`global install` copies the agents, routing assets, hooks, and
+`codex-kit-reconcile-agents` skill into `${CODEX_HOME:-~/.codex}`. It adds only
+codex-kit's hook handlers and preserves unrelated settings and hooks.
 
-```sh
-cd /path/to/project
-pnpm dlx @iamdevlinph/codex-kit@latest project init
+The default root configuration is:
+
+```toml
+model = "gpt-5.6-sol"
+model_reasoning_effort = "low"
+plan_mode_reasoning_effort = "high"
 ```
 
-`project init` performs the initial template sync, so do not run `project sync`
-immediately afterward. It creates or updates:
+Override it explicitly when needed:
 
-- `AGENTS.md`, only when missing; an existing file is preserved
-- `TEMPLATE_AGENTS.md`, a local reference copy used for future comparisons
-- `.codex-kit-state.json`, reconciliation bookkeeping
+```sh
+codex-kit global configure \
+  --orchestrator gpt-5.6-sol \
+  --reasoning-effort low \
+  --plan-reasoning-effort high
+```
 
-If `AGENTS.md` is missing or still contains only the untouched codex-kit
-scaffold, the CLI prints a clearly marked initialization prompt. Copy everything
-between `BEGIN CODEX INITIALIZATION PROMPT` and
-`END CODEX INITIALIZATION PROMPT` into a Codex task opened at the project root.
-The prompt asks Codex to verify that the project has enough substantive code,
-dependencies, configuration, and scripts to derive reliable guidance. If not,
-Codex stops without inventing rules or marking the template applied. Finish
-scaffolding the project, rerun `project init`, and send the new CLI prompt.
+`--model` is an alias for `--orchestrator`. Before changing managed values,
+codex-kit creates a timestamped `config.toml` backup and records the previous
+values. `global uninstall` restores them without replacing unrelated later edits.
+Modified managed files are preserved.
 
-When `AGENTS.md` already contains guidance, `project init` preserves it and
-prints the reconciliation prompt described below instead.
+Use `codex-kit global list` to inspect model settings, routing and hook status,
+the reconciliation skill, and installed agents. Use `codex-kit global uninstall`
+to remove package-managed global files.
 
-## Synchronize template updates
+## Project workflow
 
-After a newer codex-kit template is released, refresh an initialized project:
+Run `codex-kit project init` after the project has enough code, dependencies,
+configuration, and scripts for Codex to derive reliable guidance. It creates:
 
-```sh
-pnpm dlx @iamdevlinph/codex-kit@latest project sync
-```
+- `AGENTS.md` only when missing; existing guidance is preserved;
+- `TEMPLATE_AGENTS.md` as the local template reference;
+- `.codex-kit-state.json` for reconciliation bookkeeping.
 
-`project sync` never edits `AGENTS.md` or project skills. It routes Codex to the
-global `codex-kit-reconcile-agents` skill, which inspects project state and
-existing skills, merges only applicable reusable changes, preserves local
-adaptations and organization, and may create or update a concrete conditional
-workflow under `.agents/skills`. Critical safety, authorization, secrets,
-database, deployment, and destructive-operation rules remain in `AGENTS.md`;
-do not copy the complete template or introduce managed markers. After semantic
-reconciliation and validation, record the applied template hash:
+Initialization includes the first template sync. When the CLI prints an
+initialization or reconciliation prompt, copy the complete marked block into a
+Codex task opened at the project root.
 
-The CLI prints a clearly marked reconciliation prompt. Copy everything between
-`BEGIN CODEX RECONCILIATION PROMPT` and `END CODEX RECONCILIATION PROMPT` into a
-Codex task opened at the project root. That prompt tells Codex to validate and
-then run:
+After installing a newer package version, refresh the reference template:
 
 ```sh
-codex-kit project mark-applied
+codex-kit project sync
 ```
 
-You normally do not run that command manually.
-
-`mark-applied` updates only `.codex-kit-state.json`; it does not validate or
-modify `AGENTS.md`.
+`project sync` never edits `AGENTS.md` or project skills. The reconciliation skill
+compares the refreshed template with the project's guidance and merges only
+applicable rules while preserving local organization and adaptations. If
+`TEMPLATE_AGENTS.md` was modified locally, sync preserves it for review instead
+of overwriting it.
 
-If `TEMPLATE_AGENTS.md` was modified locally, synchronization preserves it and
-asks for review instead of overwriting it. Use `--force` only after intentionally
-discarding the local candidate changes.
-
-### Synchronize multiple projects
-
-Install the CLI once and keep a local path list:
+After reconciliation and validation, Codex runs:
 
 ```sh
-pnpm add --global @iamdevlinph/codex-kit
-
-while IFS= read -r repo; do
-  [ -n "$repo" ] && codex-kit project sync --cwd "$repo"
-done < ~/.config/codex-kit/projects.txt
+codex-kit project mark-applied
 ```
 
-Update global agents and routing separately when those assets change:
+`mark-applied` only updates `.codex-kit-state.json`; it does not validate or
+modify `AGENTS.md`. Use `codex-kit project status` to check whether the current
+template still needs reconciliation.
 
-```sh
-pnpm add --global @iamdevlinph/codex-kit@latest
-codex-kit global install
-```
+## Options
+
+- `--codex-home PATH` selects a Codex home for global commands instead of
+  `CODEX_HOME` or `~/.codex`.
+- `--cwd PATH` selects a project directory for project commands instead of the
+  current directory.
+- `--force` lets `global install`, `global configure`, `project init`, or
+  `project sync` replace modified files they manage. Use it only when you intend
+  to discard those local changes.
 
-## Check for a new version
+Examples:
 
 ```sh
-codex-kit version check
+codex-kit global install --codex-home /path/to/.codex
+codex-kit project sync --cwd /path/to/project
 ```
 
-The command queries the public npm registry only when requested. Normal project
-commands do not add network latency or depend on registry availability.
-
 ## Requirements
 
 - Node.js 20 or newer
 - Codex with custom subagent and lifecycle-hook support
 
-The published package has no runtime dependencies and uses only Node.js
-standard-library modules.
-
-## License
-
-This repository and the published `@iamdevlinph/codex-kit` package are licensed
-under the [ISC License](LICENSE).
+The published package contains no credentials or runtime dependencies. Version
+checks contact the public npm registry only when `codex-kit version check` runs.
 
-## Security
+## Security and license
 
 See [SECURITY.md](SECURITY.md) for supported versions and private vulnerability
-reporting instructions.
+reporting. This repository and package use the [ISC License](LICENSE).
 
 ## References
 

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
 
@@ -113,6 +129,10 @@ conditional procedures into validated project skills.
 - For behavior changes and bug fixes, add or update the smallest focused
   automated tests that meaningfully prevent regression when the repository has
   an established test setup.
+- Treat existing tests as regression contracts. Preserve their assertions unless
+  the requested behavior intentionally changes. When behavior changes, update
+  only the affected tests and add coverage for the new contract; never weaken or
+  delete tests merely to make the suite pass.
 - Do not introduce a test framework or create low-value tests solely to satisfy
   this rule. If automated coverage is impractical, explain why and perform the
   strongest targeted verification available.
@@ -129,12 +149,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`,

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/bin/codex-kit.js

@@ -747,18 +747,17 @@ function markApplied(options) {
 }
 
 // src/version.ts
-import { spawnSync } from "node:child_process";
-function compareVersions(left, right) {
-  const parse2 = (value) => {
-    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
-    if (!match) throw new Error(`Invalid package version: ${value}`);
-    return {
-      numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
-      prerelease: match[4] ?? null
-    };
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
+  if (!match) throw new Error(`Invalid package version: ${value}`);
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ?? null
   };
-  const a = parse2(left);
-  const b = parse2(right);
+}
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
   for (const [leftNumber, rightNumber] of [
     [a.numbers[0], b.numbers[0]],
     [a.numbers[1], b.numbers[1]],
@@ -772,27 +771,35 @@ function compareVersions(left, right) {
     a.prerelease.localeCompare(b.prerelease, "en", { numeric: true })
   );
 }
-function checkVersion() {
-  let latest = process.env.CODEX_KIT_LATEST_VERSION;
-  if (!latest) {
-    const result = spawnSync(
-      process.platform === "win32" ? "pnpm.cmd" : "pnpm",
-      ["view", PACKAGE.name, "version", "--json", `--registry=${REGISTRY}`],
-      { encoding: "utf8", timeout: 15e3 }
+async function fetchLatestVersion() {
+  const url = `${REGISTRY}/${encodeURIComponent(PACKAGE.name)}/latest`;
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(15e3) });
+  } catch (error) {
+    throw new Error(
+      `Unable to check ${REGISTRY}: ${error instanceof Error ? error.message : String(error)}`
     );
-    if (result.error)
-      throw new Error(`Unable to run pnpm: ${result.error.message}`);
-    if (result.status !== 0)
-      throw new Error(
-        `Unable to check ${REGISTRY}: ${result.stderr.trim() || "pnpm view failed"}`
-      );
-    try {
-      const value = JSON.parse(result.stdout);
-      latest = Array.isArray(value) && typeof value.at(-1) === "string" ? value.at(-1) : typeof value === "string" ? value : void 0;
-    } catch {
-      latest = result.stdout.trim();
-    }
   }
+  if (!response.ok)
+    throw new Error(
+      `Unable to check ${REGISTRY}: ${response.status} ${response.statusText}`
+    );
+  let value;
+  try {
+    value = await response.json();
+  } catch {
+    throw new Error("Registry returned no package version.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.version !== "string")
+    throw new Error("Registry returned no package version.");
+  const latest = value.version;
+  parseVersion(latest);
+  return latest;
+}
+async function checkVersion() {
+  let latest = process.env.CODEX_KIT_LATEST_VERSION;
+  if (!latest) latest = await fetchLatestVersion();
   if (!latest) throw new Error("Registry returned no package version.");
   console.log(`Installed: ${PACKAGE.version}`);
   console.log(`Latest:    ${latest}`);
@@ -897,7 +904,7 @@ Examples:
   codex-kit project sync --cwd /path/to/project --force
   codex-kit project status --cwd /path/to/project`);
 }
-function main(argv = process.argv.slice(2)) {
+async function main(argv = process.argv.slice(2)) {
   const options = parse(argv);
   if (options.positionals.includes("--version") || options.positionals.includes("-v")) {
     console.log(PACKAGE.version);
@@ -919,14 +926,14 @@ function main(argv = process.argv.slice(2)) {
   else if (scope === "project" && action === "status") projectStatus(options);
   else if (scope === "project" && action === "mark-applied")
     markApplied(options);
-  else if (scope === "version" && action === "check") checkVersion();
+  else if (scope === "version" && action === "check") await checkVersion();
   else throw new Error(`Unknown command: ${options.positionals.join(" ")}`);
 }
 
 // src/codex-kit.ts
 if (process.argv[1] && realpathSync(resolve3(process.argv[1])) === realpathSync(fileURLToPath2(import.meta.url))) {
   try {
-    main();
+    await main();
   } catch (error) {
     console.error(
       `error: ${error instanceof Error ? error.message : String(error)}`

package/package.json

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