TenantAtlas/.github/skills/spec-kit-end-to-end/SKILL.md

name: spec-kit-end-to-end description: End-to-end Spec Kit workflow for TenantPilot/TenantAtlas: select the next suitable spec candidate from roadmap/spec-candidates when needed, create or update spec.md/plan.md/tasks.md, optionally implement the active spec, run tests, browser smoke checks where applicable, post-implementation analysis, fix confirmed findings, and repeat until no in-scope findings remain or a stop condition is reached.

Skill: Spec Kit End-to-End Workflow

Purpose

Use this skill to run an end-to-end Spec Kit workflow for TenantPilot/TenantAtlas.

This skill supports three modes:

1. Preparation only: select or scope the next suitable feature from roadmap/spec-candidates and create or update spec.md, plan.md, and tasks.md.
2. Implementation only: implement an already prepared spec, run tests/checks, run strict post-implementation analysis, fix confirmed findings, and repeat until clean or a bounded stop condition is reached.
3. End-to-end: select or create a spec and then implement it in the same invocation, but only when the user explicitly requests end-to-end execution.

The intended workflow is:

feature idea / roadmap item / spec candidate / active spec
→ determine requested mode
→ inspect repo truth, constitution, roadmap, spec candidates, existing specs, and relevant code
→ create or update spec.md + plan.md + tasks.md when preparation is needed
→ evaluate quality gates
→ implement only when the user explicitly asks for implementation or end-to-end execution
→ run relevant tests/checks
→ run browser smoke test when UI/user-facing flows are affected
→ run strict post-implementation analysis
→ fix confirmed in-scope findings
→ repeat test + analysis + fix loop until clean or bounded stop condition is reached
→ final report

When to Use

Use this skill when the user asks for any Spec Kit workflow around TenantPilot/TenantAtlas, including:

• selecting the next best spec candidate from docs/product/spec-candidates.md and roadmap sources
• turning a feature idea, roadmap item, or candidate into spec.md, plan.md, and tasks.md
• preparing Spec Kit artifacts in one pass
• implementing an existing or newly prepared spec
• running implementation followed by strict analysis and fix iterations
• executing a full end-to-end flow from candidate selection to implementation verification

Typical user prompts:

Nimm den nächsten sinnvollen Spec Candidate aus Roadmap/spec-candidates und mach spec, plan und tasks.

Mach daraus spec, plan und tasks in einem Rutsch, aber noch nicht implementieren.

Erstelle die Spec Kit Artefakte und implementiere sie danach mit Analyse/Fix-Loop.

Implementiere die aktive Spec und analysiere danach, ob alles passt.

Mach Spec Kit implement und danach analyse. Behebe alle Abweichungen und wiederhole bis sauber.

Run end-to-end: choose next spec, create spec/plan/tasks, implement, analyze, fix until no in-scope findings remain.

Hard Rules

• Work strictly repo-based.
• Use the repository's actual Spec Kit workflow, scripts, templates, branch naming rules, and generated paths when available.
• Determine the requested mode before changing files:
  • preparation only
  • implementation only
  • end-to-end preparation plus implementation
• Do not implement application code unless the user explicitly asks for implementation, implement, or end-to-end execution.
• When in preparation-only mode, create or update only Spec Kit preparation artifacts unless repository conventions require additional documentation artifacts.
• When in implementation mode, implement only the active or explicitly named Spec Kit feature.
• Do not manually invent spec numbers, branch names, or spec paths if Spec Kit provides a script or command for that.
• Do not bypass Spec Kit branch mechanics.
• Do not expand scope beyond the selected feature, spec.md, plan.md, and tasks.md.
• Do not silently add roadmap features, adjacent UX rewrites, speculative architecture, or unrelated refactors.
• Follow the repository constitution and existing Spec Kit conventions.
• Preserve TenantPilot/TenantAtlas terminology.
• Prefer small, reviewable, implementation-ready specs and patches over broad rewrites.
• Treat repository truth as authoritative over assumptions.
• If repository truth conflicts with the user-provided draft or spec, keep repository truth and document the deviation.
• If repository truth conflicts with implementation scope, stop and report the conflict unless there is an obvious minimal correction inside active spec scope.
• Fix only confirmed findings from tests, static checks, or post-implementation analysis.
• Fix all confirmed in-scope findings, regardless of severity, when they are safe and bounded.
• Do not leave Medium/Low findings open silently. If they are not fixed, document exactly why.
• Never hide failing tests, weaken assertions, delete meaningful coverage, or mark tasks complete without implementation evidence.
• Do not run destructive commands.
• Do not force checkout, reset, stash, rebase, merge, or delete branches.
• Do not perform database-destructive actions unless the repository test workflow explicitly requires isolated test database resets.
• Do not continue analysis/fix loops indefinitely.
• Do not move from preparation to implementation unless the Spec Readiness Gate passes or the user explicitly accepts the documented readiness risks.
• Do not move from implementation to final status unless the Test Gate, Browser Smoke Test Gate where applicable, and Post-Implementation Analysis Gate have been evaluated.
• Do not claim merge-readiness unless the Merge Readiness Gate passes.

Required Inputs

The user should provide at least one of:

• feature title and short goal
• full spec candidate
• roadmap item
• rough problem statement
• UX or architecture improvement idea
• explicit spec directory such as specs/<number>-<slug>/
• instruction to use the current active Spec Kit feature
• instruction to choose the next best candidate from roadmap/spec-candidates

If the input is incomplete, proceed with the smallest reasonable interpretation and document assumptions.

If implementation is requested but the active spec cannot be determined safely, inspect the repository Spec Kit context first. If it is still ambiguous, stop and ask for the specific spec directory.

Required Repository Checks

Always check the sources relevant to the requested mode.

For preparation mode, always check:

1. .specify/memory/constitution.md
2. .specify/templates/
3. .specify/scripts/
4. existing Spec Kit command usage or repository instructions, if present
5. current branch and git status
6. specs/
7. docs/product/spec-candidates.md
8. relevant roadmap documents under docs/product/, especially roadmap.md if present
9. nearby existing specs with related terminology or scope
10. application code only as needed to avoid wrong naming, wrong architecture, duplicate concepts, impossible tasks, duplicated specs, or already-completed candidates

For implementation mode, always check:

1. active Spec Kit context / current branch
2. git status
3. .specify/memory/constitution.md
4. the active spec directory
5. spec.md
6. plan.md
7. tasks.md
8. relevant templates or conventions under .specify/templates/
9. nearby existing specs with related terminology or scope
10. application code surfaces referenced by the active spec
11. existing tests related to the changed behavior

Git and Branch Safety

Before running any Spec Kit command or making implementation changes:

1. Check the current branch.
2. Check whether the working tree is clean.
3. If there are unrelated uncommitted changes, stop and report them. Do not continue.
4. If the working tree only contains user-intended planning edits for this operation, continue cautiously.
5. Let Spec Kit create or switch to the correct feature branch when that is how the repository workflow works.
6. Do not force checkout, reset, stash, rebase, merge, or delete branches.
7. Do not overwrite existing specs.

If the repo requires an explicit branch creation script for specify, use that script rather than manually creating the branch.

Mode Selection

Select exactly one mode per invocation unless the user explicitly asks for end-to-end execution.

Preparation Only

Use when the user asks to:

• create spec/plan/tasks
• prepare a feature
• choose the next best spec candidate
• turn roadmap/spec-candidates into a spec
• run specify/plan/tasks/analyze without implementation
• avoid implementation

Output is limited to Spec Kit preparation artifacts, preparation-artifact fixes, and final preparation summary.

Implementation Only

Use when the user asks to:

• implement an active spec
• run Spec Kit implement
• analyze after implementation
• fix implementation findings

Requires an existing active or explicitly named spec.

End-to-End

Use only when the user explicitly asks to:

• choose/create the spec and then implement it
• run the full workflow
• go from candidate to implementation
• prepare and implement in one pass

End-to-end mode must keep preparation and implementation phases clearly separated.

End-to-end mode must pass the Candidate Selection Gate and Spec Readiness Gate before implementation begins.

Quality Gates

Quality gates are mandatory checkpoints. They make the workflow safe for agentic execution without allowing uncontrolled scope expansion.

Gate 1: Candidate Selection Gate

Required before creating a new spec from roadmap/spec-candidates.

Pass criteria:

• The selected candidate exists in roadmap/spec-candidate material or is directly provided by the user.
• The selected candidate is not already covered by an existing active or completed spec.
• The selected candidate aligns with current roadmap priorities or explicitly documented product direction.
• The candidate can be scoped as a small, reviewable, implementation-ready slice.
• Major adjacent concerns are listed as follow-up candidates instead of being hidden inside the primary scope.

Fail behavior:

• If no candidate satisfies the gate, stop and report the top candidates plus the reason none is ready.
• Do not invent a new roadmap direction to force progress.

Gate 2: Spec Readiness Gate

Required before implementation starts, including end-to-end mode.

Pass criteria:

• spec.md, plan.md, and tasks.md exist.
• The spec has clear problem statement, user value, functional requirements, out-of-scope boundaries, acceptance criteria, assumptions, and risks.
• The plan identifies likely affected repo surfaces and does not contradict repository architecture.
• The tasks are small, ordered, verifiable, and include test/validation tasks.
• RBAC, workspace/tenant isolation, auditability, OperationRun semantics, evidence/result-truth, and UX requirements are addressed where relevant.
• No open question blocks safe implementation.
• The scope is small enough for a bounded implementation loop.

Fail behavior:

• In preparation-only mode, report the readiness gaps and provide the manual analysis prompt.
• In end-to-end mode, stop before implementation unless the user explicitly asked to proceed despite the documented readiness risks.
• Do not compensate for an unclear spec by inventing implementation scope.

Gate 3: Implementation Scope Gate

Required before changing application code.

Pass criteria:

• The active spec directory is known.
• The implementation target is traceable to specific tasks in tasks.md.
• The affected files/surfaces are consistent with plan.md or clearly justified by repository truth.
• No required change would introduce unrelated product behavior.
• No required change conflicts with constitution, existing architecture, RBAC/isolation boundaries, or source-of-truth semantics.

Fail behavior:

• Stop before code changes and report the conflict or ambiguity.
• Suggest a minimal spec/plan/tasks correction if the issue is in the artifacts rather than the codebase.

Gate 4: Test Gate

Required after implementation and after each fix iteration.

Pass criteria:

• Targeted tests for changed behavior pass.
• Relevant existing tests pass or failures are proven unrelated and documented.
• Static analysis, linting, formatting, or type checks used by the repository pass when applicable.
• Security/governance-relevant changes have backend, policy, or domain coverage; UI-only verification is not enough.
• Regression coverage exists for each fixed Blocker or High finding where practical.

Fail behavior:

• Fix in-scope failures before post-implementation analysis.
• If failures are unrelated or pre-existing, document evidence and continue only if they do not invalidate the active spec.
• Do not weaken tests to pass the gate.

Gate 5: Browser Smoke Test Gate

Required before claiming implementation is ready for manual review/merge when the change affects Filament UI, Livewire interactions, navigation, forms, tables, actions, modals, dashboards, operation drilldowns, tenant/workspace context, or any user-facing flow.

Not required for documentation-only, spec-only, backend-only, domain-only, enum-only, contract-only, or test-only changes unless those changes alter a user-facing flow.

Pass criteria:

• The relevant page or flow loads in a real browser or the repository's browser-testing harness.
• The primary action introduced or changed by the spec can be executed successfully.
• Expected UI states, labels, badges, actions, empty states, tables, forms, modals, and navigation are visible where relevant.
• Workspace/tenant context is preserved across the tested flow where relevant.
• RBAC/capability-dependent visibility behaves as expected where practical to verify.
• Livewire interactions complete without visible runtime errors.
• No relevant browser console errors occur.
• No failed network requests occur for the tested flow, except known unrelated development noise that is explicitly documented.
• OperationRun, audit, evidence, result, or support-diagnostic drilldowns work where relevant.
• The smoke-tested path is documented in the final response.

Fail behavior:

• Fix in-scope browser, UX, Livewire, navigation, or runtime failures before claiming merge-readiness.
• If a browser issue is unrelated existing debt, document evidence and residual risk.
• Do not treat a passing browser smoke test as a substitute for backend, policy, domain, security, feature, or integration tests.
• Do not expand the smoke test into a full E2E suite unless the user explicitly asks for that.

Gate 6: Post-Implementation Analysis Gate

Required after implementation and after each fix iteration.

Pass criteria:

• The implementation has been checked against spec.md, plan.md, tasks.md, and constitution.
• All completed tasks have implementation evidence.
• No confirmed in-scope findings remain.
• Medium/Low findings are fixed when they are inside active spec scope, clearly bounded, and safe.
• Medium/Low findings that remain open are explicitly documented with one of these reasons:
  • out of scope
  • requires separate spec
  • risky refactor
  • existing unrelated debt
  • not reproducible
  • blocked by unclear product/architecture decision
• No scope expansion was introduced during fixes.

Fail behavior:

• Fix confirmed in-scope findings, regardless of severity, when the fix is safe and bounded.
• Stop instead of fixing when remediation would expand scope, contradict repo architecture, introduce risky refactors, or repeat the same failed fix twice.

Gate 7: Merge Readiness Gate

Required before claiming the implementation is ready for manual review/merge.

Pass criteria:

• Spec Readiness Gate passed.
• Implementation Scope Gate passed.
• Test Gate passed.
• Browser Smoke Test Gate passed when applicable, or was explicitly marked not applicable with a reason.
• Post-Implementation Analysis Gate passed.
• tasks.md reflects actual completion status.
• No confirmed in-scope findings remain.
• All remaining findings are documented as out-of-scope, follow-up candidates, unrelated existing debt, or explicit residual risks.
• Final response includes changed files, tests/checks run, iterations performed, residual risks, and follow-up candidates.

Fail behavior:

• Do not claim merge-readiness.
• Report the failed gate, remaining risks, and the smallest recommended next action.

Candidate Selection Rules

When the user asks for the next best spec from roadmap/spec-candidates:

• Read docs/product/spec-candidates.md.
• Read relevant roadmap documents under docs/product/, especially roadmap.md if present.
• Check existing specs to avoid duplicates.
• Prefer candidates that align with current roadmap priorities, platform foundations, enterprise UX, RBAC/isolation, auditability, observability, and governance workflow maturity.
• Prefer candidates that unlock roadmap progress, reduce architectural drift, harden foundations, or remove known blockers.
• Prefer small, implementation-ready slices over broad platform rewrites.
• If multiple candidates are plausible, choose one primary candidate and document why it was selected.
• Add non-selected relevant candidates as follow-up spec candidates, not hidden scope.
• Do not invent a candidate if existing roadmap/spec-candidate material provides a suitable one.
• Do not pick a spec only because it is listed first.
• Evaluate the Candidate Selection Gate before creating the spec directory.

Evaluate candidates using these criteria:

1. Roadmap Fit: Does it support the current roadmap sequence or unlock the next roadmap layer?
2. Foundation Value: Does it strengthen reusable platform foundations such as RBAC, isolation, auditability, evidence, OperationRun observability, provider boundaries, vocabulary, baseline/control/finding semantics, or enterprise UX patterns?
3. Dependency Unblocking: Does it make future specs smaller, safer, or more consistent?
4. Scope Size: Can it be implemented as a narrow, testable slice?
5. Repo Readiness: Does the repo already have enough structure to implement the next slice safely?
6. Risk Reduction: Does it reduce current architectural or product risk?
7. User/Product Value: Does it produce visible operator value or make the platform more sellable without heavy scope?

Required Selection Output Before Spec Kit Execution

Before running the Spec Kit flow, identify:

• selected candidate title
• source location in roadmap/spec-candidates
• why it was selected
• why close alternatives were deferred
• roadmap relationship
• smallest viable implementation slice
• proposed concise feature description to feed into specify

The feature description must be product- and behavior-oriented. It should not be a low-level implementation plan.

Spec Kit Preparation Flow

Use this section when the selected mode is preparation-only or end-to-end.

Step 1: Determine the repository's Spec Kit command pattern

Inspect repository instructions and scripts to identify how this repo expects Spec Kit to be run.

Common locations to inspect:

.specify/scripts/
.specify/templates/
.specify/memory/constitution.md
.github/prompts/
.github/skills/
README.md
specs/

Use the repo-specific mechanism if present.

Step 2: Run specify

Run the repository's specify flow using the selected candidate and the smallest viable slice.

The specify input should include:

• selected candidate title
• problem statement
• operator/user value
• roadmap relationship
• out-of-scope boundaries
• key acceptance criteria
• important enterprise constraints

Let Spec Kit create the correct branch and spec location if that is the repo's configured behavior.

Step 3: Run plan

Run the repository's plan flow for the generated spec.

The plan input should keep the scope tight and should require repo-based alignment with:

• constitution
• existing architecture
• workspace/tenant isolation
• RBAC
• OperationRun/observability where relevant
• evidence/snapshot/truth semantics where relevant
• Filament/Livewire conventions where relevant
• test strategy

Step 4: Run tasks

Run the repository's tasks flow for the generated plan.

The generated tasks must be:

• ordered
• small
• testable
• grouped by phase
• limited to the selected scope
• suitable for later implementation or manual analysis before implementation

Step 5: Run preparation analyze

Run the repository's analyze flow against the generated Spec Kit artifacts when the repository supports it.

Analyze must check:

• consistency between spec.md, plan.md, and tasks.md
• constitution alignment
• roadmap alignment
• whether the selected candidate was narrowed safely
• whether tasks are complete enough for implementation
• whether tasks accidentally require scope not described in the spec
• whether plan details conflict with repository architecture or terminology
• whether implementation risks are documented instead of silently ignored

In preparation-only mode, do not use analyze as a trigger to implement application code.

Step 6: Fix preparation-artifact issues only

If preparation analyze finds issues, fix only Spec Kit preparation artifacts such as:

• spec.md
• plan.md
• tasks.md
• generated Spec Kit metadata files, if the repository uses them

Allowed fixes include:

• clarify requirements
• tighten scope
• move out-of-scope work into follow-up candidates
• correct terminology
• add missing tasks
• remove tasks not backed by the spec
• align plan language with repository architecture
• add missing acceptance criteria or validation tasks

Forbidden fixes in preparation-only mode include:

• modifying application code
• creating migrations
• editing models, services, jobs, policies, Filament resources, Livewire components, tests, or commands
• running implementation or test-fix loops
• changing runtime behavior

Step 7: Evaluate the Spec Readiness Gate

After preparation analyze has passed or preparation-artifact issues have been fixed, evaluate the Spec Readiness Gate.

In preparation-only mode, stop after this gate and do not implement.

Spec Directory Rules

When creating a new spec directory, use the repository's Spec Kit-generated directory or path.

If the repository does not provide a command for spec setup, use the next valid spec number and a kebab-case slug:

specs/<number>-<slug>/

The exact number must be derived from the current repository state and existing numbering conventions.

Create or update preparation artifacts inside the selected spec directory:

specs/<number>-<slug>/spec.md
specs/<number>-<slug>/plan.md
specs/<number>-<slug>/tasks.md

If the repository templates require additional preparation files, create them only when this is consistent with existing Spec Kit conventions.

spec.md Requirements

The spec must be product- and behavior-oriented. It should avoid premature implementation detail unless needed for correctness.

Include:

• Feature title
• Problem statement
• Business/product value
• Primary users/operators
• User stories
• Functional requirements
• Non-functional requirements
• UX requirements
• RBAC/security requirements
• Auditability/observability requirements
• Data/truth-source requirements where relevant
• Out of scope
• Acceptance criteria
• Success criteria
• Risks
• Assumptions
• Open questions

TenantPilot/TenantAtlas specs should preserve enterprise SaaS principles:

• workspace/tenant isolation
• capability-first RBAC
• auditability
• operation/result truth separation
• source-of-truth clarity
• calm enterprise operator UX
• progressive disclosure where useful
• no false positive calmness

plan.md Requirements

The plan must be repo-aware and implementation-oriented, but it must not make code changes by itself.

Include:

• Technical approach
• Existing repository surfaces likely affected
• Domain/model implications
• UI/Filament implications
• Livewire implications where relevant
• OperationRun/monitoring implications where relevant
• RBAC/policy implications
• Audit/logging/evidence implications where relevant
• Data/migration implications where relevant
• Test strategy
• Rollout considerations
• Risk controls
• Implementation phases

The plan should clearly distinguish where relevant:

• execution truth
• artifact truth
• backup/snapshot truth
• recovery/evidence truth
• operator next action

tasks.md Requirements

Tasks must be ordered, small, and verifiable.

Include:

• checkbox tasks
• phase grouping
• tests before or alongside implementation tasks where practical
• final validation tasks
• documentation/update tasks if needed
• explicit non-goals where useful

Avoid vague tasks such as:

Clean up code
Refactor UI
Improve performance
Make it enterprise-ready

Prefer concrete tasks such as:

- [ ] Add a feature test covering workspace isolation for <specific behavior>.
- [ ] Update <specific Filament page/resource> to display <specific state>.
- [ ] Add policy coverage for <specific capability>.

If exact file names are not known yet, phrase tasks as repo-verification tasks first rather than inventing file paths.

Preparation Scope Control

If the requested feature implies multiple independent concerns, create one primary spec for the smallest valuable slice and add a Follow-up spec candidates section.

Examples of follow-up candidates:

• assigned findings
• pending approvals
• personal work queue
• notification delivery settings
• evidence pack export hardening
• operation monitoring refinements
• autonomous governance decision surfaces

Do not force all follow-up candidates into the primary spec.

Implementation Loop

Only execute this section when the selected mode is implementation-only or end-to-end.

Execute the loop in bounded phases:

1. Evaluate the Spec Readiness Gate.
2. Evaluate the Implementation Scope Gate before changing application code.
3. Implement the active Spec Kit feature scope.
4. Run targeted tests and relevant static/dynamic checks.
5. Evaluate the Test Gate.
6. Run a Browser Smoke Test when the change affects UI/user-facing flows.
7. Evaluate the Browser Smoke Test Gate as passed, failed, or not applicable with a reason.
8. Run strict post-implementation analysis against spec, plan, tasks, constitution, changed code, changed tests, browser smoke results where applicable, and relevant existing patterns.
9. Evaluate the Post-Implementation Analysis Gate.
10. Identify confirmed findings by severity: Blocker, High, Medium, Low.
11. Fix all confirmed in-scope findings regardless of severity when safe and bounded.
12. Do not fix findings that require scope expansion, risky unrelated refactors, or architectural/product decisions outside the active spec; document them as follow-up/residual risks with reasons.
13. Re-run relevant tests and browser smoke checks where applicable after fixes.
14. Repeat test + browser smoke + analysis + fix loop until no confirmed in-scope findings remain or a stop condition is reached.
15. Evaluate the Merge Readiness Gate.
16. Report final implementation status, changed files, tests, browser smoke result, residual risks, failed/passed gates, and manual review prompt.

Stop Conditions

Stop the implementation loop when any of the following is true:

• No confirmed in-scope findings remain.
• The same finding appears twice after attempted fixes.
• A required fix conflicts with the spec, plan, constitution, or repository architecture.
• A required fix would expand scope beyond the active spec.
• A required fix would require a risky unrelated refactor.
• A required fix depends on an unresolved product or architecture decision.
• Tests reveal an unrelated pre-existing failure that cannot be safely fixed inside the active spec.
• Browser smoke testing reveals an unrelated pre-existing UI/runtime failure that cannot be safely fixed inside the active spec.
• Three analysis/fix iterations have already been completed.
• The repository state is ambiguous enough that continuing would risk damaging architecture or data semantics.

When stopping before full cleanliness, report exactly why the loop stopped and what remains.

Post-Implementation Analysis Prompt

Use this prompt internally after implementation and after each fix iteration:

Du bist ein Senior Staff Software Engineer, Software Architect und Enterprise SaaS Reviewer.

Analysiere die Implementierung der aktiven Spec streng repo-basiert.

Ziel:
Prüfe, ob die Umsetzung vollständig, konsistent, getestet und constitution-konform ist.

Prüfe gegen:
- spec.md
- plan.md
- tasks.md
- .specify/memory/constitution.md
- geänderte Anwendungscodes
- geänderte Tests
- Browser-Smoke-Test-Ergebnis, falls UI/user-facing Flows betroffen sind
- bestehende Repository-Patterns

Wichtig:
- Keine Spekulation ohne Repo-Beleg.
- Keine Scope-Erweiterung.
- Keine neuen Produktideen als Pflicht-Fixes.
- Findings nach Blocker, High, Medium, Low gruppieren.
- Für jedes Finding konkrete Datei-/Code-Belege nennen.
- Für jedes Finding eine minimale Remediation nennen.
- Separat ausweisen, welche Findings innerhalb der aktiven Spec behoben werden müssen.
- Medium/Low Findings innerhalb der aktiven Spec ebenfalls zur Behebung markieren, wenn sie sicher und bounded sind.
- Bei UI-/Filament-/Livewire-Änderungen prüfen, ob ein Browser Smoke Test durchgeführt wurde und ob der getestete Operator-Flow wirklich funktioniert.
- Findings, die nicht behoben werden sollen, nur als Follow-up/Residual Risk ausweisen, wenn sie out of scope, risky refactor, unrelated existing debt, not reproducible oder durch eine offene Produkt-/Architekturentscheidung blockiert sind.
- Wenn keine bestätigten In-Scope Findings verbleiben, klare Implementierungsfreigabe geben.

Task Completion Rules

• Keep tasks.md aligned with actual implementation status.
• Check off tasks only after the implementation and test evidence exists.
• If a task is obsolete because repository truth proves a different path, update the task note with the reason instead of silently deleting it.
• If a task cannot be completed inside scope, leave it unchecked and report why.

Testing Rules

• Add or update tests for all changed business behavior.
• Include RBAC and workspace/tenant isolation tests where relevant.
• Include OperationRun, audit, evidence, or result-truth tests where relevant.
• Prefer regression tests for every fixed Blocker or High finding.
• Add regression tests for Medium/Low findings when the behavior is important and testable without excessive churn.
• Do not weaken tests to pass the suite.
• Do not treat a green UI path as sufficient without backend or policy coverage when the behavior is security- or governance-relevant.

Browser Smoke Test Rules

Apply these rules when the active spec changes Filament UI, Livewire interactions, navigation, forms, tables, actions, modals, dashboards, operation drilldowns, tenant/workspace context, or any user-facing flow.

The browser smoke test should be narrow and focused. It is not a full E2E suite unless explicitly requested.

Minimum smoke path:

1. Open the relevant page or entry point.
2. Confirm the expected workspace/tenant context where relevant.
3. Confirm the changed or newly introduced UI element is visible.
4. Execute the primary action or interaction changed by the spec.
5. Confirm the expected result state, notification, redirect, table update, modal state, operation link, or drilldown.
6. Check for relevant console errors.
7. Check for failed network requests related to the tested flow.
8. Document the tested path in the final response.

For TenantPilot/TenantAtlas, pay special attention to:

• Filament actions and header actions
• Livewire polling, modals, validation, and actions
• workspace/tenant context preservation
• RBAC/capability-dependent action visibility
• OperationRun links and drilldown continuity
• audit/evidence/result/support-diagnostic drilldowns where relevant
• empty states, badges, labels, and decision guidance where relevant

Browser smoke testing is required for UI/user-facing changes and optional for backend-only changes.

Do not treat browser smoke success as proof that backend security, policies, domain logic, auditability, or workspace/tenant isolation are correct. Those still require automated tests or repo-based verification.

Failure Handling

If a Spec Kit command, preparation analyze phase, implementation step, test phase, browser smoke phase, or post-implementation analysis fails:

1. Stop at the relevant gate or stop condition.
2. Report the failing command or phase.
3. Summarize the error.
4. Do not attempt unrelated implementation as a workaround.
5. Suggest the smallest safe next action.

If the branch or working tree state is unsafe:

1. Stop before running Spec Kit commands or implementation changes.
2. Report the current branch and relevant uncommitted files.
3. Ask the user to commit, stash, or move to a clean worktree.

Final Response Requirements

For preparation-only mode, respond with:

1. Selected candidate and why it was chosen
2. Why close alternatives were deferred
3. Current branch after Spec Kit execution, if changed
4. Generated spec path
5. Files created or updated by Spec Kit
6. Preparation analyze result summary
7. Preparation-artifact fixes applied after analyze
8. Assumptions made
9. Open questions, if any
10. Quality gates evaluated and their result
11. Recommended next implementation prompt
12. Explicit statement that no application implementation was performed

For implementation-only or end-to-end mode, respond with:

1. Active spec directory
2. Summary of implemented changes
3. Tests/checks run and their results
4. Browser smoke test result, tested path, or not-applicable reason
5. Quality gates passed/failed and number of analysis/fix iterations performed
6. Remaining in-scope findings, if any
7. Residual risks and follow-up candidates, if relevant
8. Files changed
9. Explicit statement whether the Merge Readiness Gate passed and whether the implementation is ready for manual review/merge

Keep the final response concise, but include enough detail for the user to continue immediately.

Manual Review Prompts

For preparation-only mode, provide a ready-to-copy prompt like this, adapted to the generated spec branch/path:

Du bist ein Senior Staff Software Architect und Enterprise SaaS Reviewer.

Analysiere die neu erstellte Spec `<spec-branch-or-spec-path>` streng repo-basiert.

Ziel:
Prüfe, ob `spec.md`, `plan.md` und `tasks.md` vollständig, konsistent, implementierbar und constitution-konform sind.

Wichtig:
- Keine Implementierung.
- Keine Codeänderungen.
- Keine Scope-Erweiterung.
- Prüfe nur gegen Repo-Wahrheit.
- Benenne konkrete Konflikte mit Dateien, Patterns, Datenflüssen oder bestehenden Specs.
- Schlage nur minimale Korrekturen an `spec.md`, `plan.md` und `tasks.md` vor.
- Wenn alles passt, gib eine klare Implementierungsfreigabe.

For preparation-only mode, also provide a ready-to-copy implementation prompt after analyze has passed or preparation-artifact issues have been fixed:

Du bist ein Senior Staff Software Engineer für TenantPilot/TenantAtlas.

Implementiere die vorbereitete Spec `<spec-branch-or-spec-path>` streng anhand von `tasks.md`.

Wichtig:
- Arbeite task-sequenziell.
- Ändere nur Dateien, die für die jeweilige Task notwendig sind.
- Halte dich an `spec.md`, `plan.md`, `tasks.md` und die Constitution.
- Keine Scope-Erweiterung.
- Keine Opportunistic Refactors.
- Führe passende Tests nach sinnvollen Task-Gruppen aus.
- Wenn eine Task unklar oder falsch ist, stoppe und dokumentiere den Konflikt statt frei zu improvisieren.
- Am Ende liefere geänderte Dateien, Teststatus, offene Risiken und nicht erledigte Tasks.

For implementation-only or end-to-end mode, provide a ready-to-copy prompt like this, adapted to the active spec number and slug:

Du bist ein Senior Staff Software Architect und Enterprise SaaS Reviewer.

Führe eine finale manuelle Review der implementierten Spec `<spec-number>-<slug>` streng repo-basiert durch.

Ziel:
Prüfe, ob die Implementierung nach dem Agenten-Loop wirklich merge-ready ist.

Wichtig:
- Keine Implementierung.
- Keine Codeänderungen.
- Keine Scope-Erweiterung.
- Prüfe gegen spec.md, plan.md, tasks.md und constitution.md.
- Prüfe die geänderten Dateien, Tests, Browser-Smoke-Test-Ergebnis, RBAC, Workspace-/Tenant-Isolation, Auditability, UX und OperationRun-Semantik, soweit relevant.
- Benenne nur konkrete Findings mit Repo-Beleg.
- Gib am Ende eine klare Entscheidung: Merge-ready, merge-ready with notes, oder not merge-ready.

Example Invocations

User:

Nutze den Skill spec-kit-end-to-end.
Wähle aus roadmap.md und spec-candidates.md die nächste sinnvollste Spec.
Führe danach GitHub Spec Kit specify, plan, tasks und analyze in einem Rutsch aus.
Behebe alle analyze-Issues in den Spec-Kit-Artefakten.
Keine Application-Implementierung.

Expected behavior:

1. Inspect constitution, Spec Kit scripts/templates, specs, roadmap, and spec candidates.
2. Check branch and working tree safety.
3. Compare candidate suitability.
4. Select the next best candidate.
5. Evaluate the Candidate Selection Gate.
6. Run the repository's real Spec Kit specify flow, letting it handle branch/spec setup.
7. Run the repository's real Spec Kit plan flow.
8. Run the repository's real Spec Kit tasks flow.
9. Run the repository's real Spec Kit preparation analyze flow.
10. Fix analyze issues only in Spec Kit preparation artifacts.
11. Evaluate the Spec Readiness Gate.
12. Stop before application implementation.
13. Return selection rationale, branch/path summary, artifact summary, analyze summary, fixes applied, gates, and next implementation prompt.

User:

Implementiere die aktive Spec. Danach analyse gegen spec/plan/tasks/constitution ausführen, alle in-scope Findings beheben und wiederhole bis sauber.

Expected behavior:

1. Inspect active Spec Kit context, constitution, spec, plan, tasks, relevant code, and relevant tests.
2. Evaluate the Spec Readiness Gate and Implementation Scope Gate.
3. Implement only the active spec scope.
4. Run targeted tests and relevant checks.
5. Evaluate the Test Gate.
6. Run and evaluate Browser Smoke Test when UI/user-facing flows are affected.
7. Run post-implementation analysis.
8. Fix all confirmed in-scope findings regardless of severity when safe and bounded.
9. Repeat test + browser smoke + analysis + fix loop up to the stop conditions.
10. Evaluate the Merge Readiness Gate.
11. Report final status, changed files, tests, browser smoke result, residual risks, gates, and manual review prompt.

User:

Run end-to-end: wähle die nächste sinnvolle Spec aus spec-candidates/roadmap, erstelle spec/plan/tasks, implementiere sie danach und wiederhole analyse/fix bis sauber.

Expected behavior:

1. Run preparation mode first.
2. Clearly report the selected candidate and created spec directory.
3. Continue into implementation mode only because the user explicitly requested end-to-end execution.
4. Implement only the newly created active spec scope.
5. Run tests/checks, browser smoke checks where applicable, post-implementation analysis, and bounded fix iterations.
6. Fix all confirmed in-scope findings regardless of severity when safe and bounded.
7. Report final implementation status, gates, browser smoke result, and residual risks.