ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
332f6325cb
TenantAtlas/specs/416-tenantpilot-agent-skill-layer-v1/plan.md
ahmido 332f6325cb feat: add tenantpilot agent skill layer v1 (#483) 
Automated PR provided by Codex via Gitea API.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #483
2026-06-25 23:03:47 +00:00

13 KiB
Raw Blame History

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)

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

.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

docs: add TenantPilot agent skill layer and router