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:

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:

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

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

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

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

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:

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

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:

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.