ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
ddf8dda525
TenantAtlas/specs/416-tenantpilot-agent-skill-layer-v1/spec.md
Ahmed Darrazi ddf8dda525
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m28s
Details
feat: add tenantpilot agent skill layer v1
2026-06-26 00:59:40 +02:00

24 KiB
Raw Blame History

Feature Specification: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration

Feature Branch: 416-tenantpilot-agent-skill-layer-v1 Created: 2026-06-25 Corrected: 2026-06-25 Status: Corrected / Ready for implementation Input: User correction request to include both TenantPilot Agent Skill Layer V1 and AGENTS.md router integration.

Purpose

Spec 416 creates the first minimal reusable TenantPilot Agent Skill Layer V1 and integrates a router rule into AGENTS.md so agents know how to activate the correct skills before repository work.

The corrected scope intentionally includes both:

  • Agent Skill Layer V1 under .agent/skills/**.
  • Router Integration in AGENTS.md.

This is repository workflow/documentation work only. It must not implement Laravel runtime behavior, product UI behavior, tests, migrations, seeders, config, routes, resources, services, policies, jobs, package files, or application dependencies.

Correction Summary

  • The original draft targeted .codex/skills/** only.
  • This correction changes the implementation target to .agent/skills/** as the skill library.
  • AGENTS.md becomes the activation/router entry point.
  • The corrected spec must not split basic router integration into a future Spec 417.
  • Any previous implementation-report evidence for .codex/skills/** is superseded by this correction and must not be treated as merge evidence for the corrected scope.

Spec Candidate Check (mandatory - SPEC-GATE-001)

  • Problem: TenantPilot agent rules are spread across AGENTS.md, the constitution, specs, audit findings, product-surface contracts, guidelines, and repeated prompts. Without a router entry point, agents can miss the skill layer entirely.
  • Today's failure: A skill layer without AGENTS.md routing is discoverable only when the current model/session already knows to look for it. Future agents need a mandatory lightweight entry point before repository work.
  • User-visible improvement: No product UI changes. The improvement is workflow safety: future agents are instructed to inspect the router, activate relevant hard gates, report activated skills, and stop before implementation when hard-gate stop conditions trigger.
  • Smallest enterprise-capable version: One .agent/skills/README.md, the scoped V1 SKILL.md files, and one concise AGENTS.md router section. Optional docs/agent-workflow.md is allowed only if AGENTS.md would otherwise become too large.
  • Explicit non-goals: No generic enterprise standards library, no 50+ skill zoo, no runtime behavior, no test/migration/config/product changes, no package changes, no huge duplicated AGENTS.md, and no requirement to load every skill by default.
  • Permanent complexity imported: A repository skill library, a router rule in AGENTS.md, a skill taxonomy/maturity vocabulary, and maintenance responsibility when repo truth changes.
  • Why now: The repo has accumulated validated contracts around workspace scope, RBAC, OperationRun truth, customer output, evidence anchors, provider freshness, Product Surface, Filament/Livewire, browser audit, and TCM cutover. These must be reusable without relying on long prompts.
  • Approval class: Cleanup / Consolidation.
  • Red flags triggered: New meta-infrastructure and foundation-like wording. Defense: the layer is repo-specific, bounded, documentation/workflow-only, and explicitly forbids broad standards skills or runtime frameworks.
  • Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 10/12
  • Decision: approve as a bounded preparation package after this correction.

Spec Scope Fields (mandatory)

  • Scope: repository workflow/documentation only.
  • Future implementation files allowed: .agent/skills/**, AGENTS.md, optional docs/agent-workflow.md, and specs/416-tenantpilot-agent-skill-layer-v1/**.
  • Primary Routes: N/A - no application route or rendered UI surface is added or changed.
  • Data Ownership: N/A - no runtime data ownership or persistence changes.
  • RBAC: N/A for application authorization behavior. The skills must encode RBAC and workspace isolation guidance for future work.

Deliverables

  1. Create .agent/skills/README.md.
  2. Create the V1 skill files under .agent/skills/**.
  3. Update AGENTS.md with a TenantPilot Agent Skill Router section.
  4. Optionally create docs/agent-workflow.md only if the router section would exceed 12 lines or would need to duplicate skill details inside AGENTS.md.
  5. Keep the implementation documentation/workflow-only.
  6. Do not modify runtime behavior.

Required Skill Structure

.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

AGENTS.md Router Integration Requirements

AGENTS.md must include a concise router rule equivalent to:

## TenantPilot Agent Skill Router

Before starting any repository task, inspect `.agent/skills/README.md`.
Activate only the skills relevant to the requested task.
Do not load all skills by default.
Before implementation or review, report:
- activated skills
- why each skill was activated
- branch
- HEAD
- dirty state
- hard-gate stop conditions, if any

Hard-gate skills are blocking. If a hard-gate stop condition is met, stop before implementation and report the blocker.
Prefer current repo evidence, active specs, tests, and validated contracts over historical prompts or inventory-only specs.
Inventory-only specs are hints, not hard evidence.
Temporary migration skills must include expiry or review criteria.

The router must make clear:

  • .agent/skills/** is the skill library.
  • AGENTS.md is the activation/router entry point.
  • Agents must not load all skills by default.
  • Agents must read .agent/skills/README.md before repository work.
  • Agents must activate only relevant skills based on task triggers.
  • Agents must report activated skills and reasons before implementation or review.
  • Hard-gate skill stop conditions block implementation.
  • Current repo evidence beats historical prompts.
  • Inventory-only specs are hints, not hard evidence.
  • Temporary skills require expiry or review conditions.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable product UI surface?

  • No UI surface impact
  • Existing page changed
  • New page/route added
  • Navigation changed
  • Filament panel/provider surface changed
  • New modal/drawer/wizard/action added
  • New table/form/state added
  • Customer-facing surface changed
  • Dangerous action changed
  • Status/evidence/review presentation changed
  • Workspace/environment context presentation changed

UI/Productization Coverage

N/A - no reachable product UI surface impact. This spec creates repository workflow/documentation artifacts only. It must not change Filament resources/pages, Livewire components, Blade views, routes, navigation, actions, modals, tables, forms, customer output, report surfaces, review/evidence surfaces, or provider/restore UI.

Product Surface Impact

Reference: docs/product/standards/product-surface-contract.md.

  • Product Surface Contract applies?: no - no rendered product surface changes.
  • Page archetype: N/A.
  • Primary user question: N/A.
  • Primary action: N/A.
  • Surface budget result: N/A.
  • Technical Annex / deep-link demotion: N/A - no product view changes.
  • Canonical status vocabulary: N/A - no product-facing labels added.
  • Visible complexity impact: neutral for rendered product UI.
  • Product Surface exceptions: none.

Browser Verification Plan (mandatory)

  • Browser proof required?: no.
  • No-browser rationale: N/A - no rendered UI surface changed.
  • Focused path when required: N/A.
  • Primary interaction to execute: N/A.
  • Console, Livewire, Filament, network, and 500-error checks: N/A.
  • Full-suite failure triage: N/A unless implementation unexpectedly changes rendered UI, which is out of scope and requires spec amendment.

Human Product Sanity Check (mandatory)

  • Required?: no rendered product sanity.
  • No-human-sanity rationale: N/A - no product surface changed.
  • Workflow sanity target: Reviewers should verify the skill layer and router are smaller and clearer than repeated prompt blocks, do not create false authority over repo truth, and do not require agents to load every skill by default.

Cross-Cutting / Shared Pattern Reuse

  • Cross-cutting feature?: yes, repository-workflow only.
  • Interaction class(es): agent skill activation, implementation/review guardrails, documentation workflow.
  • Systems touched: .agent/skills/**, AGENTS.md, optional docs/agent-workflow.md, and this spec package.
  • Existing pattern(s) to extend: existing repository-level agent instructions and skill SKILL.md convention.
  • Allowed deviation and why: .agent/skills/** is the corrected skill-library target for router integration. .codex/skills/** is not the corrected implementation target for Spec 416.
  • Consistency impact: Each skill must use the required section template and activation/stop-condition language to avoid parallel prompt styles.
  • Review focus: Confirm the implementation does not add runtime frameworks, generic standards-only skills, a huge AGENTS.md, or load-all-by-default behavior.

OperationRun UX Impact

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

Provider Boundary / Platform Core Check

  • Shared provider/platform boundary touched?: no runtime seam touched.
  • Boundary classification: N/A.
  • Neutral platform terms preserved or introduced: Skills must preserve current constitution language: workspace, managed environment, provider connection, provider-owned metadata, operation, governed subject, evidence, and customer-safe output.
  • Provider-specific semantics retained and why: Microsoft/Graph may appear only as current repo evidence or examples inside skills, not as platform-core truth.
  • Why this does not deepen provider coupling accidentally: No application code or platform-core runtime contract changes.
  • Follow-up path: none for basic router usage.

Proportionality Review (mandatory when structural complexity is introduced)

  • New source of truth?: no product/runtime source of truth. Yes, a repository workflow guidance source for agent activation is introduced.
  • New persisted entity/table/artifact?: no runtime persistence. Yes, repository documentation/workflow artifacts under .agent/skills/** and AGENTS.md.
  • New abstraction?: yes, a small agent skill layer plus a router rule for existing repo contracts.
  • New enum/state/reason family?: no runtime enum/state family. Skill maturity and gate type labels are documentation taxonomy only.
  • New cross-domain UI framework/taxonomy?: no runtime UI framework. Product Surface skill must explicitly forbid turning Product Surface guidance into runtime presenter/framework code.
  • Current operator problem: Future agents need a reliable way to activate the correct existing repo contract before repository work.
  • Existing structure is insufficient because: Rules exist but are distributed; a skill layer alone is not enough unless AGENTS.md routes agents to it.
  • Narrowest correct implementation: One .agent/skills/README.md, the listed V1 skills, and one concise AGENTS.md router section.
  • Ownership cost: Skills and router must be kept current when constitution, Product Surface Contract, Filament baseline, RBAC contracts, OperationRun contracts, provider freshness semantics, customer/evidence gates, or workflow rules materially change.
  • Alternative intentionally rejected: Generic enterprise standards library, 50+ skill zoo, automatic all-skill loading, runtime frameworks, and a separate future spec for basic router integration.
  • Release truth: current-release workflow truth based on completed/recent specs and current repo guidance.

Testing / Lane / Runtime Impact (mandatory)

  • Test purpose / classification: N/A for Laravel runtime; repository artifact verification only.
  • Validation lane(s): N/A for app/Pest/browser/PostgreSQL lanes. Use read-only shell checks for files, headings, router text, quarantine/path constraints, and final diff scope.
  • Why this classification and these lanes are sufficient: The spec creates markdown workflow artifacts and updates AGENTS.md. Runtime test suites would not prove this docs/workflow behavior.
  • New or expanded test families: none.
  • Fixture / helper cost impact: none.
  • Heavy-family visibility / justification: none.
  • Special surface test profile: N/A.
  • Test governance outcome: keep - artifact/router verification remains the narrowest sufficient lane because no runtime behavior, tests, fixtures, helpers, browser coverage, or heavy-governance family changes.
  • Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage - N/A - no rendered UI surface changed.

User Scenarios & Testing (mandatory)

User Story 1 - Select the right TenantPilot contract skill (Priority: P1)

As an implementation or review agent, I want a compact skill README that tells me which TenantPilot skill to activate for a task so I do not load every historical spec or miss the relevant guardrail.

Independent Test: Inspect .agent/skills/README.md and confirm it lists all V1 skills, activation triggers, maturity/gate types, quarantine warnings, currentness rules, and "do not load all skills by default".

User Story 2 - Route future agents through AGENTS.md (Priority: P1)

As a future agent entering the repository, I want AGENTS.md to route me to .agent/skills/README.md before repository work so the skill layer is actually used.

Independent Test: Inspect AGENTS.md and confirm the TenantPilot Agent Skill Router section includes the required router rules, branch/HEAD/dirty-state reporting, hard-gate blocking semantics, and current-evidence preference.

User Story 3 - Execute repo-contract hard gates honestly (Priority: P1)

As an implementation or review agent, I want each hard-gate skill to state activation conditions, source evidence, required repo context, execution checklist, stop conditions, and required evidence after use.

Independent Test: For every L4 hard-gate skill, verify all required headings exist and stop conditions include concrete failure modes from the current constitution, validated specs, and repo source evidence.

User Story 4 - Preserve quarantine and temporary-skill honesty (Priority: P2)

As a reviewer, I want the skill layer and router to identify historical or temporary rules that must not be preserved as current truth.

Independent Test: Inspect the README, relevant skills, and AGENTS.md router for the quarantine list, current-repo-evidence preference, inventory-only hint rule, and temporary skill expiry/review requirements.

Edge Cases

  • The implementation must stop if it would create a generic SOC2/GDPR/SSDF/enterprise-best-practice skill.
  • The implementation must stop if it would require agents to load all skills by default.
  • The implementation must stop if any runtime/app/test/migration/config/package file change is needed.
  • The implementation must document any missing source-evidence file instead of inventing support.
  • The implementation must stop if the router would turn AGENTS.md into a duplicated copy of all skills.

Functional Requirements

  • FR-416-001: The implementation MUST create .agent/skills/README.md as the V1 skill-layer index.
  • FR-416-002: The README MUST state that the skill layer is not a replacement for specs, tests, code review, current repo truth, or the TenantPilot constitution.
  • FR-416-003: The README MUST instruct agents not to load all skills by default and to activate skills by task trigger.
  • FR-416-004: The README MUST include the maturity model L0 through L4 and gate type definitions.
  • FR-416-005: The README MUST include a V1 activation table covering all required skills.
  • FR-416-006: The README and relevant skills MUST quarantine these rules: tenant_id as platform-core ownership truth, Coverage v1 vocabulary as customer truth, v1-v2 adapters, fallback readers, dual writes, fallback-to-latest evidence, OperationRun as default customer proof, stale provider Healthy/Ready semantics, limited customer download vocabulary, raw provider/evidence payload default display, Product Surface runtime framework, and historical audits as current truth.
  • FR-416-007: The implementation MUST use .agent/skills/** as the skill library.
  • FR-416-008: The implementation MUST update AGENTS.md with the TenantPilot Agent Skill Router section.
  • FR-416-009: The implementation MAY create docs/agent-workflow.md only if keeping the required router guidance inside AGENTS.md would make the router exceed 12 lines or require duplicated skill details inside AGENTS.md.
  • FR-416-010: Every generated SKILL.md MUST include these headings: Purpose, Activate When, Do Not Activate When, Maturity, Gate Type, Source Evidence, External Anchors, Required Repo Context, Execution Checklist, Stop Conditions, Required Evidence After Use, Common Failure Modes, Quarantined Rules, Review / Expiry.
  • FR-416-011: If a heading is not applicable for a skill, it MUST state Not applicable. rather than being omitted.
  • FR-416-012: Create repo-contracts/workspace-scope-safety as an L4 hard-gate skill.
  • FR-416-013: Create repo-contracts/rbac-action-safety as an L4 hard-gate skill.
  • FR-416-014: Create repo-contracts/operation-run-truth as an L4 hard-gate skill.
  • FR-416-015: Create repo-contracts/customer-output-gate as an L4 hard-gate skill.
  • FR-416-016: Create repo-contracts/evidence-anchor-contract as an L4 hard-gate skill.
  • FR-416-017: Create repo-contracts/provider-freshness-semantics as an L4 hard-gate skill.
  • FR-416-018: Create repo-contracts/product-surface-gate as an L3 checklist skill.
  • FR-416-019: Create workflows/spec-readiness-gate as an L3 checklist skill.
  • FR-416-020: Create workflows/filament-livewire-v5-change-loop as an L3 checklist skill.
  • FR-416-021: Create workflows/browser-readonly-audit as an L2/L3 checklist workflow skill.
  • FR-416-022: Create temporary-migrations/tcm-cutover-guard as an L3 temporary migration gate skill.
  • FR-416-023: The TCM cutover guard MUST state that it expires after Coverage v2 / TCM activation and legacy coverage vocabulary cutover are complete.
  • FR-416-024: The implementation MUST NOT create generic standards-only skills such as soc2, gdpr, ssdf, or enterprise-best-practice.
  • FR-416-025: The implementation MUST NOT change Laravel application code, Filament resources/pages, Livewire components, policies, services, jobs, migrations, seeders, tests, runtime config, routes, views, assets, package files, or lock files.
  • FR-416-026: The implementation report MUST use the final report format defined below and end with PASS, PASS WITH CONDITIONS, or FAIL.

Allowed Final Implementation Diff

Allowed implementation changes are only:

  • .agent/skills/**
  • AGENTS.md
  • docs/agent-workflow.md (optional)
  • specs/416-tenantpilot-agent-skill-layer-v1/**

Forbidden implementation changes include:

  • app/**
  • bootstrap/**
  • config/**
  • database/**
  • routes/**
  • resources/**
  • tests/**
  • composer.json
  • composer.lock
  • package.json
  • package-lock.json
  • pnpm-lock.yaml
  • yarn.lock
  • vite.config.*
  • tailwind.config.*

Non-Goals

Spec 416 must not:

  • create a generic enterprise standards library
  • create a 50+ skill zoo
  • modify application/runtime behavior
  • change tests
  • change migrations
  • change config
  • change product behavior
  • change packages or lock files
  • turn AGENTS.md into a huge duplicated copy of all skills
  • require agents to load every skill by default
  • split basic router integration into a future Spec 417

Acceptance Criteria

Skill Layer

  • All required skill files exist under .agent/skills/**.
  • .agent/skills/README.md exists and functions as the skill-layer index.
  • The README states that active specs, tests, code review, current repo truth, and constitution override skill text.
  • The README tells agents not to load all skills by default.
  • Every required SKILL.md includes all required headings.
  • README and relevant skills include applicable quarantine rules.
  • No generic standards-only skill files are created.
  • temporary-migrations/tcm-cutover-guard/SKILL.md contains explicit expiry/review language.

Router Integration

  • AGENTS.md contains a TenantPilot Agent Skill Router section.
  • The router tells agents to read .agent/skills/README.md.
  • The router tells agents to activate only relevant skills.
  • The router tells agents not to load all skills by default.
  • The router tells agents to report activated skills and reasons before implementation or review.
  • The router treats hard-gate stop conditions as blockers.
  • The router requires branch, HEAD, and dirty state before file changes.
  • The router says current repo evidence beats historical prompts.
  • The router says inventory-only specs are hints, not hard evidence.
  • The router says temporary skills require expiry/review criteria.

Scope Safety

  • Final diff contains only allowed paths.
  • Runtime files changed: no.
  • Tests changed: no.
  • Migrations changed: no.
  • Config changed: no.
  • Routes/resources/services/policies/jobs/package files changed: no.
  • Browser proof remains N/A - no rendered UI surface changed.

Verification Requirements

Required verification commands or equivalents:

find .agent/skills -name 'SKILL.md' -print | sort
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

Additional required checks:

  • heading validation for every .agent/skills/**/SKILL.md
  • no generic standards-only skill paths such as soc2, gdpr, ssdf, or enterprise-best-practice
  • TCM expiry/review language exists
  • final diff contains only allowed paths
  • forbidden runtime/test/config/package paths are absent from the diff
  • git diff --check covers tracked or staged implementation files before close-out
  • git status --short is recorded in the report

Final Report Format

The future implementation report MUST include:

A. Branch / HEAD / Dirty State B. Files Created C. Files Modified D. Skills Created E. AGENTS.md Router Added: yes/no F. Maturity / Gate Type Summary G. Quarantine Rules Included H. Verification Commands Run I. Runtime Files Changed: yes/no J. Tests Changed: yes/no K. Migrations Changed: yes/no L. Config Changed: yes/no M. PASS / PASS WITH CONDITIONS / FAIL

Suggested Commit Message

docs: add TenantPilot agent skill layer and router

Risks

  • The router can become stale if the skill library moves or if the constitution changes.
  • AGENTS.md can become too long if it duplicates skill content instead of routing to the README.
  • Too many skills can encourage broad context loading. V1 mitigates this through a small list and progressive disclosure.
  • Skills can become false authority if they are not kept subordinate to current repo evidence, active specs, tests, validated contracts, and the constitution.

Assumptions

  • .agent/skills/** is the corrected implementation target for Spec 416.
  • AGENTS.md is the repository entry point that future agents are expected to read.
  • Runtime app behavior is not needed to make the skill router useful.
  • Optional docs/agent-workflow.md should be avoided unless the router section would exceed 12 lines or would need to duplicate skill details inside AGENTS.md.
  • Existing inventory-only specs are hints and must not be treated as hard current evidence without validation.

Open Questions

None blocking implementation.