TenantAtlas/.github/skills/spec-kit-next-best-one-shot/SKILL.md

---
name: spec-kit-next-best-one-shot
description: Select the most suitable next TenantPilot/TenantAtlas spec from roadmap and spec-candidates, then run the GitHub Spec Kit preparation flow in one pass: specify, plan, tasks, and analyze. Use when the user wants the agent to choose the next best spec, execute the real Spec Kit workflow including branch/spec-directory mechanics, analyze the generated artifacts, and fix preparation issues before implementation. This skill must not implement application code.
---

# Skill: Spec Kit Next-Best One-Shot Preparation

## Purpose

Use this skill when the user wants the agent to select the most suitable next spec from existing product planning sources and then execute the real GitHub Spec Kit preparation flow in one pass:

1. select the next best spec candidate from roadmap and spec candidates
2. run the repository's Spec Kit `specify` flow for that selected candidate
3. run the repository's Spec Kit `plan` flow for the generated spec
4. run the repository's Spec Kit `tasks` flow for the generated plan
5. run the repository's Spec Kit `analyze` flow against the generated artifacts
6. fix issues in Spec Kit preparation artifacts only (`spec.md`, `plan.md`, `tasks.md`, and related Spec Kit metadata if required)
7. stop before implementation
8. provide a concise readiness summary for the user

This skill must use the repository's actual Spec Kit scripts, commands, templates, branch naming rules, and generated paths. It must not manually bypass Spec Kit by creating arbitrary spec folders or files. The only allowed fixes after `analyze` are preparation-artifact fixes, not application-code implementation.

The intended workflow is:

```text
roadmap.md + spec-candidates.md
→ select next best spec
→ run Spec Kit specify
→ run Spec Kit plan
→ run Spec Kit tasks
→ run Spec Kit analyze
→ fix preparation-artifact issues
→ explicit implementation step later
```

## When to Use

Use this skill when the user asks things like:

```text
Nimm die nächste sinnvollste Spec aus roadmap und spec-candidates und führe specify, plan, tasks und analyze aus.
```

```text
Wähle die nächste geeignete Spec und mach den Spec-Kit-Flow inklusive analyze in einem Rutsch.
```

```text
Schau in roadmap.md und spec-candidates.md und starte daraus specify, plan, tasks und analyze.
```

```text
Such die beste nächste Spec aus und bereite sie per GitHub Spec Kit vollständig vor.
```

```text
Nimm angesichts Roadmap und Spec Candidates das sinnvollste nächste Thema, aber nicht implementieren.
```

## Hard Rules

- Work strictly repo-based.
- Use the repository's actual GitHub Spec Kit workflow.
- Do not manually invent spec numbers, branch names, or spec paths if Spec Kit provides a script or command for that.
- Do not manually create `spec.md`, `plan.md`, or `tasks.md` when the Spec Kit workflow can generate them.
- Do not bypass Spec Kit branch mechanics.
- Run `analyze` after `tasks` when the repository supports it.
- Fix only issues found in Spec Kit preparation artifacts and planning metadata.
- Do not treat analyze findings as permission to implement product code.
- If analyze reports implementation work as missing, record it in `tasks.md` instead of implementing it.
- Do not implement application code.
- Do not modify production code.
- Do not modify migrations, models, services, jobs, Filament resources, Livewire components, policies, commands, or tests unless the user explicitly starts a later implementation task.
- Do not execute implementation commands.
- Do not run destructive commands.
- Do not invent roadmap priorities not supported by repository documents.
- Do not pick a spec only because it is listed first.
- Do not select broad platform rewrites when a smaller dependency-unlocking spec is more appropriate.
- Prefer specs that unlock roadmap progress, reduce architectural drift, harden foundations, or remove known blockers.
- Prefer small, reviewable, implementation-ready specs over large ambiguous themes.
- Preserve TenantPilot/TenantAtlas terminology.
- Follow the repository constitution and existing Spec Kit conventions.
- If repository truth conflicts with roadmap/candidate wording, keep repository truth and document the deviation.
- If no candidate is suitable, do not run Spec Kit commands and explain why.

## Required Repository Checks Before Selection

Before selecting the next spec, inspect:

1. `.specify/memory/constitution.md`
2. `.specify/templates/`
3. `.specify/scripts/`
4. existing Spec Kit command usage or repository instructions, if present
5. `specs/`
6. `docs/product/spec-candidates.md`
7. roadmap documents under `docs/product/`, especially `roadmap.md` if present
8. nearby existing specs related to top candidate areas
9. current branch and git status
10. application code only as needed to verify whether a candidate is already done, blocked, duplicated, or technically mis-scoped

Do not edit application code.

## Git and Branch Safety

Before running any Spec Kit command or script:

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.

## Candidate Selection Criteria

Evaluate candidate specs using these criteria.

### 1. Roadmap Fit

Prefer candidates that directly support the current roadmap sequence or unlock the next roadmap layer.

Examples:

- governance foundations before advanced compliance views
- evidence/snapshot foundations before auditor packs
- control catalog foundations before CIS/NIS2 mappings
- decision/workflow surfaces before autonomous governance
- provider/platform boundary cleanup before multi-provider expansion

### 2. Foundation Value

Prefer candidates that strengthen reusable platform foundations:

- RBAC and workspace/tenant isolation
- auditability
- evidence and snapshot truth
- operation observability
- provider boundary neutrality
- canonical vocabulary
- baseline/control/finding semantics
- enterprise detail-page or decision-surface patterns

### 3. Dependency Unblocking

Prefer specs that unblock multiple later candidates.

A good next spec should usually make future specs smaller, safer, or more consistent.

### 4. Scope Size

Prefer a candidate that can be implemented as a narrow, testable slice.

Avoid selecting:

- broad platform rewrites
- vague product themes
- multi-feature bundles
- speculative future-provider frameworks
- large UX redesigns without a clear first slice

### 5. Repo Readiness

Prefer candidates where the repository already has enough structure to implement the next slice safely.

Check whether related models, services, UI pages, tests, or concepts already exist.

### 6. Risk Reduction

Prefer candidates that reduce current architectural or product risk:

- legacy dual-world semantics
- unclear truth ownership
- inconsistent operator UX
- missing audit/evidence boundaries
- repeated manual workflow friction
- false-positive calmness in governance surfaces

### 7. User/Product Value

Prefer specs that produce visible operator value or make the platform more sellable without creating 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 Execution Flow

After selecting the candidate, execute the real repository Spec Kit preparation sequence, including analysis and preparation-artifact fixes.

### 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:

```text
.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 manual analysis before implementation

### Step 5: Run `analyze`

Run the repository's `analyze` flow against the generated Spec Kit artifacts.

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

Do not use analyze as a trigger to implement application code.

### Step 6: Fix preparation-artifact issues only

If 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 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: Stop

After `analyze` has passed or preparation-artifact issues have been fixed, stop.

Do not implement.
Do not modify application code.
Do not run implementation tests unless the repository's Spec Kit preparation command requires a non-destructive validation.

## Failure Handling

If a Spec Kit command or analyze phase fails:

1. Stop immediately.
2. Report the failing command or phase.
3. Summarize the error.
4. Do not attempt 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.
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

After the Spec Kit preparation flow completes, respond with:

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

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

## Required Next Implementation Prompt

Always provide a ready-to-copy implementation prompt like this, adapted to the generated spec branch/path, but only after analyze has passed or preparation-artifact issues have been fixed:

```markdown
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.
```

## Example Invocation

User:

```text
Nutze den Skill spec-kit-next-best-one-shot.
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. Run the repository's real Spec Kit `specify` flow, letting it handle branch/spec setup.
6. Run the repository's real Spec Kit `plan` flow.
7. Run the repository's real Spec Kit `tasks` flow.
8. Run the repository's real Spec Kit `analyze` flow.
9. Fix analyze issues only in Spec Kit preparation artifacts.
10. Stop before application implementation.
11. Return selection rationale, branch/path summary, artifact summary, analyze summary, fixes applied, and next implementation prompt.
```