TenantAtlas/specs/416-tenantpilot-agent-skill-layer-v1/plan.md

# Implementation Plan: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration

**Branch**: `416-tenantpilot-agent-skill-layer-v1` | **Date**: 2026-06-25 | **Spec**: `specs/416-tenantpilot-agent-skill-layer-v1/spec.md`

## Summary

Create a minimal TenantPilot-specific agent skill library under `.agent/skills/**` and integrate a concise TenantPilot Agent Skill Router into `AGENTS.md`. The router makes the skill layer usable by future agents by requiring them to inspect `.agent/skills/README.md`, activate only relevant skills, report activated skills and reasons, and stop when hard-gate conditions trigger.

This remains repository workflow/documentation work only. It must not alter TenantPilot Laravel runtime behavior, product UI behavior, tests, migrations, routes, config, package files, assets, lock files, or application code.

## Technical Context

**Language/Version**: Markdown repository artifacts; application baseline remains PHP 8.4.15, Laravel 12, Filament 5, Livewire 4.
**Primary Dependencies**: Repository agent instructions in `AGENTS.md`; skill file convention (`SKILL.md`) under `.agent/skills/**`.
**Storage**: Git-tracked markdown files only; no database/storage changes.
**Testing**: Read-only shell verification; no Pest/runtime/browser tests unless implementation unexpectedly changes runtime files, which is out of scope.
**Validation Lanes**: artifact checks, router grep checks, heading checks, final diff scope checks, `git diff --check`, `git status --short`.
**Target Platform**: repository workflow for AI coding agents.
**Project Type**: Laravel monorepo with Spec Kit and project-level agent instructions.
**Performance Goals**: Skill files stay focused enough for progressive disclosure.
**Constraints**: no runtime files, no generic standards-only skill zoo, no completed-spec rewrite, no load-all-by-default router, no huge duplicated `AGENTS.md`.
**Scale/Scope**: one README, 11 V1 skills, one concise router section, optional workflow doc only if needed.

## Existing Repo Truth

- `AGENTS.md` is the repository entry point for agent instructions.
- `.agent/skills/**` does not currently provide the corrected Spec 416 skill library and must be created by implementation.
- Existing `.codex/skills/**` content is not the corrected implementation target for Spec 416.
- Related specs 395, 400, 402, 414, and 415 are context/dependency artifacts and must not be rewritten.
- Inventory-only specs are hints, not hard current evidence, unless validated by current repo source/tests/contracts.

## Affected Surfaces

- `.agent/skills/**`: new skill library and README.
- `AGENTS.md`: concise router section.
- `docs/agent-workflow.md`: optional only if the router section would exceed 12 lines or would need to duplicate skill details inside `AGENTS.md`.
- `specs/416-tenantpilot-agent-skill-layer-v1/**`: active spec package and future close-out report.

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing product surface change.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A.
- **No-impact class**: repository workflow/documentation only.
- **Required tests or manual smoke**: `N/A - no rendered UI surface changed`.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Guardrail / `N/A - no rendered UI surface changed`.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none.
- **Screenshot or page-report need**: no.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: canonical corrected skill library under `.agent/skills/**`; no `.codex/skills/**` target for this spec.
- **Page archetype and surface budget plan**: N/A.
- **Technical Annex and deep-link demotion plan**: N/A.
- **Canonical status vocabulary plan**: N/A.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: N/A for rendered product UI; workflow sanity focuses on router clarity and no scope drift.
- **Visible complexity outcome target**: rendered product UI neutral; agent workflow selection becomes explicit and bounded.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: no Livewire code changed; app baseline remains Livewire v4.
- **Panel provider registration location**: no panel provider change; Laravel panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no Filament resources changed.
- **Destructive/high-impact action posture**: no application actions changed.
- **Asset strategy**: no assets; `filament:assets` not required by this spec.
- **Testing plan**: no pages/widgets/relation managers/actions; artifact verification only.
- **Deployment impact**: none for env vars, migrations, queues, scheduler, storage, runtime assets, or Dokploy deployment.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, repository workflow/documentation only.
- **Systems touched**: `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, active spec package.
- **Shared abstractions reused**: existing `AGENTS.md` instruction entry point and skill `SKILL.md` convention.
- **New abstraction introduced? why?**: A bounded agent skill layer plus a router rule is introduced to consolidate repeated repo-contract rules and make them discoverable before work.
- **Bounded deviation / spread control**: no generic standards library, no 50+ skill zoo, no automatic all-skill loading, no runtime framework.

## AGENTS.md Router Plan

Add a concise section titled `TenantPilot Agent Skill Router` to `AGENTS.md` that requires agents to:

- inspect `.agent/skills/README.md` before repository work
- activate only relevant skills based on task triggers
- not load all skills by default
- report activated skills and reasons before implementation or review
- report branch, HEAD, dirty state, and hard-gate stop conditions
- treat hard-gate stop conditions as blocking
- prefer current repo evidence, active specs, tests, and validated contracts over historical prompts or inventory-only specs
- treat inventory-only specs as hints, not hard evidence
- require temporary migration skills to include expiry or review criteria

If this cannot remain within 12 lines in `AGENTS.md` without duplicating skill details, create `docs/agent-workflow.md` for supporting detail and keep `AGENTS.md` as the router.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no runtime seam touched.
- **Provider-owned seams**: N/A.
- **Platform-core seams**: N/A.
- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, provider metadata, operation, customer-safe output, evidence anchor.
- **Retained provider-specific semantics and why**: Microsoft/Graph can appear only as current repo evidence or examples inside skills.
- **Bounded extraction or follow-up path**: none for basic router integration.

## Constitution Check

- Inventory-first / snapshots-second: N/A - no product inventory or snapshot behavior.
- Read/write separation: N/A - no application read/write flow.
- Graph contract path: N/A - no Graph code.
- Deterministic capabilities: N/A - no capability derivation changes.
- RBAC/workspace/tenant isolation: encoded as future skill guidance; no runtime authorization changes.
- OperationRun observability: encoded as future skill guidance; no OperationRun behavior changes.
- Product Surface Contract: satisfied through no rendered product surface impact.
- Test governance: runtime/app lanes are N/A; artifact verification commands are specified.
- Proportionality: completed in `spec.md` because a new workflow/skill abstraction and router are introduced.
- No premature abstraction: allowed as a small docs/workflow consolidation based on repeated validated repo contracts.
- Provider boundary: no runtime boundary touched.
- Completed-spec guardrail: related completed specs remain read-only context.

## Test Governance Check

- **Test purpose / classification by changed surface**: N/A for Laravel runtime; artifact checks only.
- **Affected validation lanes**: N/A for app lanes.
- **Why this lane mix is the narrowest sufficient proof**: Markdown skill files and `AGENTS.md` router text can be verified through file, heading, grep, and diff-scope checks without booting Laravel.
- **Narrowest proving command(s)**:
  - `find .agent/skills -name 'SKILL.md' -print | sort`
  - heading validation for every `.agent/skills/**/SKILL.md`
  - `grep -n "TenantPilot Agent Skill Router" AGENTS.md`
  - `grep -n ".agent/skills/README.md" AGENTS.md`
  - `grep -n "Do not load all skills by default" AGENTS.md`
  - `grep -n "Hard-gate skills are blocking" AGENTS.md`
  - `grep -n "Inventory-only specs are hints" AGENTS.md`
  - no generic standards-only skill paths
  - final diff contains only allowed paths
  - forbidden runtime/test/config/package paths are absent from the diff
  - `git diff --check`
  - `git status --short`
- **Fixture / helper / factory / seed / context cost risks**: none.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Budget / baseline / trend follow-up**: none.
- **Test governance outcome**: `keep` - artifact/router checks remain the correct validation lane because this spec adds no runtime behavior, test lane, fixture/helper, browser, or heavy-governance cost.
- **Review-stop questions**: Did implementation create the `.agent` library? Did it add the AGENTS router? Did it create generic standards-only skills? Did it change runtime files? Did it force all skills to load? Did it treat inventory-only specs as hard evidence?
- **Why no dedicated follow-up spec is needed**: Spec 416 now includes basic router integration.

## Project Structure

### Documentation (this feature)

```text
specs/416-tenantpilot-agent-skill-layer-v1/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- implementation-report.md
`-- checklists/
    `-- requirements.md
```

### Repository artifacts to be created during implementation

```text
.agent/
  skills/
    README.md
    repo-contracts/
      workspace-scope-safety/SKILL.md
      rbac-action-safety/SKILL.md
      operation-run-truth/SKILL.md
      customer-output-gate/SKILL.md
      evidence-anchor-contract/SKILL.md
      provider-freshness-semantics/SKILL.md
      product-surface-gate/SKILL.md
    workflows/
      spec-readiness-gate/SKILL.md
      filament-livewire-v5-change-loop/SKILL.md
      browser-readonly-audit/SKILL.md
    temporary-migrations/
      tcm-cutover-guard/SKILL.md
```

**Structure Decision**: Use `.agent/skills/**` because the corrected feature requires a general skill library routed from `AGENTS.md`. Do not target `.codex/skills/**` for the corrected Spec 416 implementation.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| New docs/workflow skill layer | Repeated validated repo contracts are spread across many files and prompts | Prompt-only repetition is fragile and not discoverable during long agent sessions |
| Router section in `AGENTS.md` | Future agents must know to inspect the skill library before work | A standalone skill library can be missed without an entry point |
| Maturity/gate taxonomy in skill files | Agents need to know when a skill is a hard gate versus checklist guidance | Free-form prose makes stop conditions and authority unclear |

## Phase 0: Repo Verification

Confirm current branch, HEAD, clean/dirty state, existing skill roots, no committed `.agent/skills/**` package for this spec, and completed-spec guardrail for related specs.

## Phase 1: Skill Index

Create `.agent/skills/README.md` with purpose, progressive disclosure, activation table, maturity model, gate definitions, V1 skill list, quarantine rules, currentness warning, inventory-only hint warning, and temporary-skill warning.

## Phase 2: Skill Files

Create the required L4 hard-gate, L3 checklist, L2/L3 workflow, and L3 temporary migration skills under the required `.agent/skills/**` structure.

## Phase 3: Router Integration

Update `AGENTS.md` with the TenantPilot Agent Skill Router section. Create `docs/agent-workflow.md` only if the router would exceed 12 lines or duplicate skill details inside `AGENTS.md`.

## Phase 4: Verification And Report

Run read-only artifact checks, router grep checks, final diff-scope checks, confirm no runtime files changed, and write the implementation report under the active spec package.

## Out Of Scope

- Laravel runtime code.
- Filament/Livewire resources, pages, widgets, actions, views, assets, or providers.
- Migrations, models, services, jobs, policies, commands, routes, seeders, factories, tests, config, package files, or lock files.
- Generic enterprise standards skill library.
- 50+ skill zoo.
- Requiring agents to load every skill by default.
- Completed-spec rewrites.

## Suggested Commit Message

```text
docs: add TenantPilot agent skill layer and router
```