agrimap-agent-skills

Routing skill plus dedicated one-operation AgriMap engineering skills

Open source Open in the app JSON README (API)

About

Routing skill plus dedicated one-operation AgriMap engineering skills

Details

Kind: Plugins
Topic: No topic detected
Publisher: orchex006
Origin: gemini
Category: ferramentas
Version: 2.1.0
Last push: 2026-07-29T06:58:56Z
Repository state: ativo
Language: JavaScript
Added: 2026-08-30 14:13:39
Updated: 2026-08-30 14:13:39
Origin id: orchex006/agrimap-agent-skills

README

# agrimap-agent-skills

Official AgriMap engineering skill package by Billy. Each of the 16 `agm-*` skills owns one operation. The `agrimap-agent-skills` umbrella is a routing-only selector and never executes an operation or acts as a fallback workflow.

แพ็กเกจรวม dedicated skills สำหรับ analysis, diagnosis, simulation, planning, design, architecture, review, FE/BE/SQL refactor, QA, unit tests, feature creation, prompt delegation, execution และ history โดยแยก trigger/workflow ต่อ operation.

## Design

```text
skills/agrimap-agent-skills/ routing-only skill + shared resources/scripts
│
├── compact runtime core + generated operation entrypoints
├── Codex plugin skills ($agrimap-agent-skills, $agm-*)
├── Claude plugin skills (/agrimap-agent-skills:agm-*)
└── Gemini extension commands (/agm-*) + routing skill

project/.agrimap-agent/ execution memory, daily logs, tracked tasks, raw history, Prompt Results, reports
project/.agrimap-agent/runtime/ ignored per-session identity + active tasks + hook refresh state
```

### Authored source and generated plugin mirror

- Author and review the routing skill, shared references, assets, and scripts only under `skills/agrimap-agent-skills/`.
- `plugins/agrimap-agent-skills/skills/agrimap-agent-skills/` is a generated byte-for-byte mirror of the routing skill and shared resources. Never edit that mirror directly.
- `.rgignore` excludes that byte-for-byte mirror from default repo-wide `rg` searches, so authored content appears once. Use `rg --no-ignore` only when explicitly auditing generated copies; validation still compares every mirrored byte.
- `config/operations.json` owns each dedicated skill's compact inputs, mode, instructions, and reference route. `npm run sync` generates `references/operation-index.md`, `references/operations/*.md`, Codex/Claude operation skills, and Gemini commands from it.
- `plugins/agrimap-agent-skills/skills/agm-*` read exactly `lifecycle-core.md` plus their one generated operation contract. The glossary and technical references load only when that contract/depth requires them.
- This repository is detected as `skill-package` from its manifest, operation registry, and lifecycle source. Package/meta work edits canonical package surfaces and never creates root FE/BE/SQL product artifacts unless the requester explicitly authorizes an exact fixture/example path.
- Run `npm run sync` after every canonical or operation change. Normal package tests and validation reject mirror drift.

The package does not import legacy `.agm` governance and does not create an extra permission layer. Platform permissions remain authoritative. Preserved legacy code samples are compatibility evidence only and are hash-verified.

## Requirements

- Git
- Node.js 20 or newer for hooks and workspace/index scripts
- one supported host: Codex, Claude Code, or Gemini CLI

Repository: [gasxhermvc/agrimap-agent-skills](https://github.com/gasxhermvc/agrimap-agent-skills)

Usage guide: [docs/USAGE.md](docs/USAGE.md) — provider syntax, activation proof, all operation examples, large text, images, attachments, and pointed files/lines.

## Install for Codex

```powershell
codex plugin marketplace add gasxhermvc/agrimap-agent-skills
codex plugin add agrimap-agent-skills@agrimap-agent-skills
```

Start a new Codex session after installation. In Codex CLI, `/plugins` can also browse and install the plugin after the marketplace is added. Invoke `$agrimap-agent-skills` only to choose an operation; invoke a domain alias such as `$agm-be action=create` to execute it.

Local repository testing:

```powershell
codex plugin marketplace add .
codex plugin add agrimap-agent-skills@agrimap-agent-skills
```

## Install for Claude Code

From a terminal:

```powershell
claude plugin marketplace add gasxhermvc/agrimap-agent-skills
claude plugin install agrimap-agent-skills@agrimap-agent-skills
```

Or run the equivalent `/plugin marketplace add` and `/plugin install` commands inside Claude Code. Installed skill names are namespaced, for example:

```text
/agrimap-agent-skills:agrimap-agent-skills
/agrimap-agent-skills:agm-be action=create
/agrimap-agent-skills:agm-prompt
```

Local validation and installation:

```powershell
claude plugin validate .
claude plugin marketplace add .
claude plugin install agrimap-agent-skills@agrimap-agent-skills
```

## Install for Gemini CLI

Run from the terminal, not from Gemini's interactive prompt:

```powershell
gemini extensions install https://github.com/gasxhermvc/agrimap-agent-skills
```

Restart Gemini CLI after installation. Invoke `/agm-be action=create`, `/agm-plan`, or another generated command. For local development:

```powershell
gemini extensions link .
```

### How Gemini loads bundled references

Gemini sandboxes its file tools to the workspace root, so a globally installed extension cannot let the model read its own bundled contract and reference files. The extension therefore ships a read-only stdio MCP server (`skills/agrimap-agent-skills/scripts/mcp-server.mjs`) declared in `gemini-extension.json` under `mcpServers.agrimap`. Gemini launches it once at startup as a subprocess, resolving `${extensionPath}` to the install directory, and every generated `/agm-*` command loads its `lifecycle-core.md`, operation entrypoint, and conditional references by calling the `read_reference` tool (exposed as `mcp_agrimap_read_reference`). The model keeps reading your project files with its normal, workspace-scoped file tools. Requirements: `node` on `PATH` (the same dependency the hooks already use). The server is read-only, stateless, and runs as one isolated subprocess per Gemini instance — using stdio rather than a fixed port — so opening several projects at once never collides. Codex and Claude are unaffected: they resolve the same references through their own plugin host, not this server.

## Provider hook isolation

Provider identity is host-specific: Codex selects `plugins/agrimap-agent-skills/hooks/codex-hooks.json`, Claude selects `claude-hooks.json`, and Gemini alone uses the repository-root `hooks/hooks.json`. The shared Codex/Claude plugin root must not contain a default `hooks/hooks.json`, because both hosts can auto-discover it. Release `0.1.7` makes SQLFluff the cosmetic-layout owner and requires complete changed-file coverage; reinstall/sync it before retesting so hosts do not retain an older cached alias.

The plugin hooks are installed globally but non-candidates inspect only activation inputs (Git root/origin name, activation config, explicit prompt syntax, and the session active-task marker); they inject no context, read no identity or memory, and write no state. Generated skill bodies apply the same boundary before loading AgriMap lifecycle references, covering implicit model selection as well as hooks. Activation requires the Git root/remote name to match an AgriMap project, the current prompt to explicitly invoke a registered alias using provider-native syntax, the session to have an active tracked task, or `.agrimap-agent/config.json` to set `activation.auto` to `true`. Recognized one-repository/one-project names are `agmwa-<letters-and-hyphens>-ng`, `agmws-<letters-and-hyphens>-netcore`, `agmbo-<letters-and-hyphens>-netcore`, `agrimap-<letters-and-hyphens>`, and `AgriMap.<dot-separated-letters>`. Digits, underscores, arbitrary `agm-*` text, and `.agrimap-agent` directory existence alone do not activate the hook.

For an active candidate without an explicit alias or active task, narrow task-mode detection adds an operation gate only when Primary SQL product intent is present: an SQL action plus a strong SQL target such as a `.sql` path or stored procedure. It requires the dedicated `agm-sql` operation before inspection or writes but grants no write authority. Mentions of `agm-sql`, skills, hooks, plugins, packages, or routing are meta intent and do not trigger product SQL routing.

Gemini may show its native consent prompt when activating a skill or fingerprinting a hook. The package does not add a second approval gate.

## Workflow depth and first tracked use

Each operation declares default and allowed workflow depths in `config/operations.json`. Every started execution persists requester attribution plus concise current/recent memory and daily JSONL audit evidence. `light` creates **no `tasks/**` artifacts**. `standard|regulated` use `tasks/YYYY-MM/<ddHHmmss>/` and complete exactly `brief.md`, `analysis.md`, `checklists.md`, `qa.md`, and `result.md` by phase. The selector and lifecycle rules live in [`lifecycle-core.md`](skills/agrimap-agent-skills/references/lifecycle-core.md).

On the first `standard` or `regulated` interaction, the Leader resolves who is requesting the work. In a multi-person project there is no shared `owner.json`.

Requester identity and decision authority are separate. Every `standard`/`regulated` task records requester authority (`owner|delegated|requester-only|unknown`), the decision owner, and authority evidence; a requester without owner/delegated authority cannot approve a material trade-off. Normative terms live in [`glossary.md`](skills/agrimap-agent-skills/references/glossary.md).

- ignored live identity: `.agrimap-agent/runtime/sessions/<session-id>.json`, confirmed for a bounded window (24 hours by default)
- ignored active task: `.agrimap-agent/runtime/active/<session-id>.json`
- tracked attribution: who requested what in tracked briefs (when applicable) and versioned daily JSONL events with exact UTC timestamps
- execution attribution: actual `model`, optional configurable `modelLabel`, `role`, `agent`, and `provider` are separate; `requestedBy` remains the human
- change context: schema-v4 daily events use snake_case, separate `execution_id` from nullable light `task_id`, and record workflow depth, log type, canonical milestones, and Git snapshot fields

This is workflow attribution, not proof of the physical editor or commit author. Use `$agm-history` for requester/executor/task chronology and Git log/blame separately for actual commit authorship. `recordedFiles` contains only valid versioned non-terminal claims; any `legacyClaimedFiles` are diagnostic and are not promoted into that attribution. Check `auditStorage` before relying on the result across machines: ignored or untracked logs are local-only. JSONL is not cryptographically tamper-evident; use an external immutable audit system if that threat model applies.

If any activated operation lacks a confirmed human, the hook instructs the agent to resolve that identity before task start. The hook never copies the requester from the latest shared log.

Manual bootstrap or diagnostics:

```powershell
node <installed-package>\skills\agrimap-agent-skills\scripts\agm-workspace.mjs init --cwd .
node <installed-package>\skills\agrimap-agent-skills\scripts\agm-workspace.mjs identify --cwd . --session <session-id> --requested-by "Billy" --model-label "GPT-5.6-sol" --model "<host-reported-model>" --role leader --agent primary --provider codex
node <installed-package>\skills\agrimap-agent-skills\scripts\agm-workspace.mjs start --cwd . --session <session-id> --depth light --operation prompt --title "Prepare shared-table Prompt Result" --requester-authority owner --decision-owner "Billy" --authority-evidence "confirmed in this session"
node <installed-package>\skills\agrimap-agent-skills\scripts\agm-workspace.mjs checkpoint --cwd . --session <session-id> --execution <ddHHmmss> --milestone acceptance-slice --summary "Shared table slice completed" --files "src/a.ts,src/b.ts" --verification "typecheck passed"
```

Project policy decides which durable `.agrimap-agent/` evidence is tracked. Raw requester submits without AI answers append to `prompts/YYYY-MM/<conversation>/history.md`; immutable Prompt Results use `prompts/YYYY-MM/<conversation>/<context>-vNNN.md`; execution-generated role instructions live in `instructions/`. Never commit `.agrimap-agent/runtime` or `.agrimap-agent/cache`.

## Operations

| Alias | Purpose |
| --- | --- |
| `agm-analyze` | cross-discipline evidence-led analysis |
| `agm-design` | unified FE/BE/SQL/architecture design, product-read-only |
| `agm-fe` | frontend analyze/design/create/edit/refactor/test actions |
| `agm-be` | backend analyze/design/create/edit/refactor/test actions |
| `agm-sql` | SQL analyze/design/create/edit/refactor/explain actions |
| `agm-diagnose` | evidence-led root cause |
| `agm-simulate` | scenarios, risks, transitions, observables |
| `agm-plan` | reverse-engineered execution plan |
| `agm-architect` | boundaries, contracts, migration |
| `agm-review` | evidence-backed findings |
| `agm-history` | read-only requester/task history by person, date, task, or event |
| `agm-qa` | product-read-only QA; direct `light` by default, tracked only when regulated |
| `agm-prompt` | light/artifactless immutable Prompt Result V1→VN with explicit Main/Subagent ownership |
| `agm-exec` | execute one decision-owner-approved prompt under task/QA rails |

Removed aliases `agm-create-feature`, `agm-create-unit-test`, `agm-create-prompt`, `agm-refactor`, and `agm-refactor-fe|be|sql` are not distributed. Use `agm-prompt`, domain `action=refactor`, and the embedded unit-test decision capability. Historical log/task operation strings remain readable.

Passive capabilities are embedded supporting skills that automatically contribute knowledge, disciplines, checks, and decision criteria to the active operation/action. They support both product-read-only and already-authorized product-write work; they do not replace the active context or independently create write intent. The mandatory Goal Rules—Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution—are one such capability. Routing is machine-readable in [`passive-skill-map.json`](skills/agrimap-agent-skills/assets/passive-skill-map.json). FE/BE work involving domain concatenation, redirects, or callbacks must select exact values from the authoritative [`application-url-matrix.md`](skills/agrimap-agent-skills/references/application-url-matrix.md), never generic fallback concatenation.

Audit examples:

```powershell
node <installed-package>\skills\agrimap-agent-skills\scripts\agm-workspace.mjs history --cwd . --from 2026-07-01 --to 2026-07-15
node <installed-package>\skills\agrimap-agent-skills\scripts\agm-workspace.mjs history --cwd . --requester Billy --days 5
```

Logs supply workflow chronology; each result distinguishes requester, executor, claimed files, Git context, and storage durability, and points to brief/result/QA/current/recent artifacts. Bare dates use UTC. Invalid versioned records are reported but excluded from evidence.

For backend creation/testing, use `target_kind=be-main` with required `backend_profile=agmws|agmbo`. These profiles are not target kinds; no generic or fallback profile exists. `be-library` does not use `backend_profile`.

## Front-end Engineer discipline

The embedded supporting discipline is automatically composed with every FE analysis, design, architecture, feature, refactor, review, test, QA, and prompt task. It augments the selected action and has no separate command. Every FE task classifies `fe-main` or `fe-library` and one phase:

- `foundation`: structure, tokens, config, development infrastructure, Core/CodeBase/SharedComponent;
- `active-development`: reuse discovery, consistency, consumer impact, technical-debt containment for multi-developer delivery;
- `stabilization`: flow completion, bugs, quality, bounded refactor, platform security checks, and deploy confidence.

Before creating a reusable function/component/service/directive/pipe/token/config, search code and `.agrimap-agent/knowledge/frontend-reuse.jsonl`. Prefer exact reuse, safe extension, or composition. Do not force reuse into an option-heavy abstraction.

```powershell
node <installed-package>\skills\agrimap-agent-skills\scripts\frontend-reuse-index.mjs scan --cwd . --paths src,projects,libs --by "Billy"
node <installed-package>\skills\agrimap-agent-skills\scripts\frontend-reuse-index.mjs search --cwd . --query "table pagination"
node <installed-package>\skills\agrimap-agent-skills\scripts\frontend-reuse-index.mjs deprecate --cwd . --id "component:src/path#Symbol" --replacement "component:src/new-path#Symbol" --by "Billy"
node <installed-package>\skills\agrimap-agent-skills\scripts\frontend-reuse-index.mjs validate --cwd .
```

Scanner results start as `discovered`. The Leader inspects suitability and promotes an entry to `verified` with `upsert`; no embedding/vector service is required in v1.

## Back-end Engineer discipline

The embedded supporting discipline is automatically composed with every BE task, augments the selected action, and has no separate command. It requires:

- `target_kind=be-main|be-library`;
- `backend_profile=agmws|agmbo` only for `be-main`;
- `phase=foundation|active-development|stabilization`.

There is no Type A/B/C and no required `change_kind`. `agmws` is the web host flow `Presentation -> Application/UseCase -> Domain -> Port -> Infrastructure -> response`. `agmbo` has no Presentation tier and starts from `Quartz/JobScheduler -> Application/UseCase -> Domain -> Port -> Infrastructure`; `Infrastructure/Jobs/JobScheduler.cs` contains scheduling concerns, never business logic.

For both `be-main` and `be-library`, request/header/cookie/query/form/body work conditionally loads the curated `013-1-extensions-request-value-normalize.md` contract. Analysis and diagnosis inventory inconsistent direct access; refactor preserves precedence, blank/null/trim, multi-value and body-buffering behavior; QA reruns representative sources. The extensions are static and add no DI registration.

Foundation reuses `agrimap.platform` before creating Core infrastructure. Active development analyzes the existing Domain first and completes the smallest vertical slice. Stabilization emphasizes regression safety, production configuration, deployment, existing vulnerability checks, and bounded refactor.

## SQL discipline

For new SQL artifacts, the normalized AgriMap golden contract outranks a project's inconsistent folder, naming, type, and comment conventions. Existing deployed schema and caller behavior remain compatibility facts and must not be broken silently.

- `action=edit|refactor` requires an exact existing target; a missing target stops `SQL_EDIT_TARGET_NOT_FOUND` and never becomes create.
- Every new artifact requires `output_owner=product|owner-reference|knowledge-draft`; unresolved ownership stops `SQL_OUTPUT_OWNER_REQUIRED`, and a missing directory is not create authority.
- With `output_owner=product`, write one SQL object per file under `sql/<GROUP_OR_DOMAIN>/table/<TABLE>.sql` or `sql/<GROUP_OR_DOMAIN>/procedure/<PROCEDURE>.sql`.
- Owner-provided or explicitly approved DDL references belong under `.agrimap-agent/knowledge/references/db-schema/`. Tentative AI-generated SQL belongs under `.agrimap-agent/knowledge/drafts/sql/` and is never schema `FACT` or deployable output without separate promotion approval.
- Any target that reads or writes data through a stored procedure, view, table, or inline SQL loads [`db-schema-context.md`](skills/agrimap-agent-skills/references/db-schema-context.md) first. It resolves owner DDL by object name, requires the tables and `LUT_*` lookups one hop past each procedure, traces a failing call from mapped error code through `THROW` and its `Validate ...` gate down to the column the predicate assumes, and reports `db-schema: <loaded>/<expected>`. Missing schema is a named `UNKNOWN` for the owner, never an inferred table, column, type, key, or constraint, and never a reason to connect to a database.
- Write guarded message inserts only to `sql/<GROUP_OR_DOMAIN>/messages.sql`, targeting `LUT_APP_MESSAGES (ID, DESCR)` with `IF NOT EXISTS`.
- Lookup tables use an `INT` key and `NAME NVARCHAR(255)`; general tables use a `NUMERIC(38,0)` key.
- Every created or edited stored procedure uses `CREATE OR ALTER PROCEDURE`; standalone `CREATE PROCEDURE`, `ALTER PROCEDURE`, `CREATE PROC`, and `ALTER PROC` fail validation. Raw-immutable golden evidence is not rewritten, so writers normalize its declaration when producing output.
- Stored procedures use `_I`, `_U`, `_D`, `_Q`, or `_CHECK_Q` according to their operation.
- Stored procedures mark validation gates, transaction boundaries, numbered business steps, and `PO_*` returns with canonical three-line section comments.

Plugin installation does not install Python packages. SQL writers draft for semantics, not cosmetic indentation/alignment, then run direct `sqlfluff format --exclude-rules "CP02, LT01, RF06" --dialect tsql <FILE>.sql` (or the approved-folder form ending in `.`) without a version probe. Only command-not-found triggers `install-sqlfluff.mjs`. Handoff requires `formatted N/N` for every changed `.sql` path and validation of the identical set. Temporary probes use OS temp with guaranteed cleanup, never the workspace. QA never installs or runs SQLFluff.

## Model labels and prompt generation

The default capability matrix preserves configurable model labels. Claude reasoning/review uses labels `fable` (displayed as Fable 5) or `opus4.8`; `fable` is also the hard-executor label, while standard/light execution uses `sonnet5`, `sonnet4.6`, or `haiku4.5`. Codex reasoning/review uses label `GPT-5.6-sol`; execution uses labels `gpt-5.6-sol`, `gpt-5.4`, or `gpt-5.4-mini`. Gemini uses `gemini-cli-default`. None of these labels proves that the current host exposes a model with that name.

These are decision-owner/project-editable routing labels, not actual-model claims. At dispatch, resolve the label against models available on the active host and record both `modelLabel` and the actual host-reported `model`; do not silently present a configured label as the running model. Override labels in `.agrimap-agent/model-capability-matrix.yaml` or the generated prompt without weakening the workflow contract.

Provider/model capability changes assignment capacity only. Fable 5, Codex, Gemini, or any reasoning-heavy profile receives the same workflow depth, QA mode, tool allowlist, and acceptance rules; a stronger model never upgrades itself to full QA.

A decision-owner-approved generated prompt is the execution SoT for exactly one task. It keeps the problem, end state, evidence, authorized decisions, file/contract ownership, ordered steps, verification, deviation policy, and Result Package together. Plain language is preferred; missing contracts are not.

## QA separation and task closure

`agm-qa` defaults to direct `depth=light qa_mode=light`. Tracked regulated work uses a separate verifier and `qa.md`; `standard` completion uses proportional writer verification and records QA as not applicable. Full QA is selected only by the exact triggers in [`qa-and-done.md`](skills/agrimap-agent-skills/references/qa-and-done.md), never merely by provider/model, target kind, data-related code, or diff size.

Both tracked depths remain schema-validated. `regulated` requires QA evidence/identity; `standard` writes `qa.md` as `not-applicable` with its proportional verification reason. Commit/publish/release boundaries require regulated depth and full QA.

QA never connects to LocalDB/dbserver/SQL Server or runs product test utilities. Executable validation is limited to AgriMap skill scripts, a necessary `dotnet build` for an existing BE project, and—only at full FE QA when startup evidence is explicitly necessary—`npm run start:agrimap:development`.

The task-artifact contract below is generated from `skills/agrimap-agent-skills/assets/task-artifact-schema.json`; edit the schema and templates, then run `npm run sync` instead of editing this table.

| Artifact | Write phase / owner | Required depths | Template | Purpose | Required fields | Required sections |
| --- | --- | --- | --- | --- | --- | --- |
| `brief.md` | `contract` the leader starting a standard/regulated execution; agm-prompt is artifactless | `standard` `regulated` | `task-brief.md` | Requester, authority, execution identity, objective, scope, ownership, and decisions. | `Task ID` `Requested by` `Identity source` `Requester authority` `Decision owner` `Authority evidence` `Model label` `Actual model` `Role` `Agent` `Provider` `Operation` `Workflow depth` `Objective` `Scope` `Non-goals` | `File and logical-contract ownership` `Inputs` `Authorized decisions and trade-offs` `Service ownership references` `Concerns` |
| `analysis.md` | `contract` leader or executor after target inspection and before implementation completion | `standard` `regulated` | `analysis.md` | Evidence-backed current state, findings, impact, and approved approach for tracked work. | — | `Current State` `Findings` `Proposed Approach` |
| `checklists.md` | `contract` the tracked execution leader initializes acceptance items; executor and leader update status | `standard` `regulated` | `checklists.md` | Checked completion ledger derived from the task contract. | — | — |
| `qa.md` | `verification` agm-qa after implementation evidence exists | `standard` `regulated` | `qa.md` | Tracked QA evidence under the canonical product-read-only verifier contract. | `Status` `QA mode` `QA mode reason` `Coverage key` `Light sequence` `Patterns` `Requested by` `Decision owner` `QA model label` `QA actual model` `QA role` `QA agent` `QA provider` `Product artifacts modified` `Workflow artifacts written` `Implementation model label` `Implementation actual model` `Implementation role` `Implementation agent` `Implementation provider` | `Requirement evidence` `Commands and observed results` `Limitations` |
| `result.md` | `closure` leader after implementation, verification, and applicable QA | `standard` `regulated` | `result.md` | Leader closure result, QA boundary, verification, memory, and outstanding work. | `Outcome` `Requested by` `Decision owner` `Leader model label` `Leader actual model` `Leader role` `Leader agent` `Leader provider` `Workflow depth` `QA status` `QA mode` `Delivery boundary` | `Authorized decisions` `Changes and verification` `Checklist and memory` `Concerns and commit boundary` `Outstanding items` |

Completion cross-artifact gates:

- Depths `light` create no task directory or task artifacts.
- Tracked start scaffolds only `brief.md` `checklists.md`; `analysis.md`, `qa.md`, and `result.md` are phase-owned completion artifacts.
- Standard completion writes `qa.md` with status `not-applicable` and records result QA status/mode as `not-applicable`.
- Regulated accepted QA statuses: `passed` `not-applicable`.
- At regulated depth, `Requested by` and `Decision owner` match across brief, QA, and result.
- Regulated QA identity (`QA actual model` `QA agent` `QA provider`) must differ from implementation identity (`Implementation actual model` `Implementation agent` `Implementation provider`).
- Delivery boundaries `commit` `publish` `release` require regulated depth and `QA mode: full`.
- A regulated full run records `Light sequence: 0`; light runs may record only `1` `2`.

Full QA is mandatory when any schema trigger applies:

1. commit, publish, or release boundary
2. same-task full re-QA after a qa-finding
3. third consecutive passed-light tracked closure for the same coverage key
4. explicit requester request for qa_mode=full or highest verification

## State and log location

The global installation is stateless. On real work, both logs and memory are written to the project currently being changed: `<target-project>/.agrimap-agent/`. The Skill/plugin installation directory is never a state destination.

This repository is the Skill's development source, so its entire `.agrimap-agent/` is local-only and ignored by Git. Repository-local `AGENTS.md` wording remains local, while the package's target-project hook independently enforces the same conversation-scoped raw-history format. Raw history, versioned Prompt Results, generated instructions, task results, reports, memory, and concise logs retain distinct ownership.

AI Gateway storage is not part of v1.

## Service ownership source of trust

Use `.agrimap-agent/knowledge/service-ownership.yaml` as the only project service/data ownership map. Analyses, prompts, decisions, and memory point to its `service_id` entries instead of copying another map. Claims are `confirmed`, `tentative`, `unknown`, or `deprecated`; only confirmed, current evidence may drive a hard ownership decision.

The package initializes an empty canonical file and intentionally does not promote the Fable service inventory with many TBD values. Migrate each useful entry after evidence review.

## Delegation and sandbox integration

The Leader must define `workspace_need` and verify whether executors share a workspace, use visible worktrees, or run in isolated sandboxes. A branch name alone is never accepted as proof that another agent's work can be integrated.

- one file and one logical contract have one writer model per integration wave;
- shared registration/export/route/DI/schema files belong to one executor or the Leader;
- overlapping work is combined or executed sequentially;
- isolated work returns a visible commit SHA, portable patch, or complete changed artifacts;
- the Leader integrates, invokes the canonical QA contract, and synthesizes evidence, so neither requester nor decision owner is left to collect agent fragments.

Every delegation prompt states isolation need, requested mode, base ref/commit, provider instruction, visibility check, integration return, and fallback. Claude Code can use custom subagent `isolation: worktree` when the installed version supports it; Codex managed worktrees are surface-dependent. Unsupported or unknown modes use only the named shared/sequential fallback. Uncommitted parent changes are never assumed visible in an isolated worktree.

Current Codex releases enable subagent workflows by default and surface activity in the app, CLI, and IDE. Before spawning, the Leader announces a descriptive label, bounded task, expected output, and inspection path for every agent. In the app, open the agent thread; in CLI use `/agent`; in the IDE expand the background-agent panel. The Leader must continue safe work or report `running|completed|blocked` status at least every 60 seconds—an unexplained 5–7 minute “Waiting for subagent…” loop is invalid. Native threads are primary; runtime progress JSONL is fallback-only and records start, meaningful phase/status transitions, and finish/block—not every step or tool call.

## License status

No license is committed yet. MIT is the recommended license for the skill engine and newly authored documentation, but preserved golden examples must first be confirmed as publishable by their rights holder or sanitized/excluded. A public repository without a license is visible but does not grant general reuse rights.

## Remaining pattern-example gaps

The package deliberately does not invent company conventions. Current collections are usable; only targeted gaps should be requested when they can change the active task:

The current FE-library architecture, naming, generated API, environment, Playground, and smoke-test baseline are already usable `current` guidance. Only the narrower gaps below retain `missing-owner-example` until decision-owner evidence is added.

- FE library minor/major semver triggers and richer assertions beyond smoke coverage;
- BE main repository/domain/response choices where neighboring code conflicts, plus representative tests;
- `agmbo` scheduler/retry/concurrency examples and run commands;
- BE library compatibility cases and representative tests beyond Playground/smoke paths;
- project-specific SQL relationship, deployed-behavior, and test conventions that the normalized golden contract does not define.

See `skills/agrimap-agent-skills/references/patterns/owner-example-intake.md` for the exact files, symbols, naming, comments, and commands to provide. Raw examples stay immutable; annotation and status live separately.

## Maintain and release

```powershell
npm run sync
npm test
npm run validate
```

Token/read coverage can be audited independently from product-code tests:

```powershell
# Every generated operation baseline plus curated FE/BE/QA/golden scenarios
npm run audit:tokens

# One scenario with every counted file
npm run audit:tokens -- --scenario qa-fe-main-golden-regulated --details

# CI mode: exit 1 on a missing route/reference or exceeded budget
npm run audit:tokens -- --scenario router-only --json
npm run audit:tokens:strict

# ทดสอบตัว audit โดยเฉพาะ
npm run test:token-coverage
```

The audit reports direct alias preload, cumulative `Load now`, and the complete selected scenario as words, characters, and an estimated token range. Estimates use 3–4 characters per token because Codex, Claude, and Gemini tokenizers differ. Scenario definitions and budgets live in `skills/agrimap-agent-skills/assets/token-coverage-scenarios.json`; use `--json` for machine-readable evidence.

`package.json` is the only package-version source of truth. `npm run sync` propagates that version to the Codex manifest, Claude manifest/marketplace, and Gemini manifest while rebuilding the operation index, compact operation entrypoints, routing-skill mirror, dedicated aliases, and provider adapters from the canonical runtime core plus `config/operations.json`. Never edit generated routing indexes, operation entrypoints, plugin mirrors, alias skills, Gemini command files, or generated manifest versions directly. Before a public release, resolve the golden-example rights/license decision, update `package.json`, add the release entry to `CHANGELOG.md`, then rerun sync, tests, and validation.

Official format references: [Codex plugins](https://developers.openai.com/codex/build-plugins), [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents), [Claude plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces), and [Gemini extensions](https://geminicli.com/docs/extensions/reference/).

agrimap-agent-skills

About

Details

README

More