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

---
name: spec-kit-one-shot-prep
description: Describe what this skill does and when to use it. Include keywords that help agents identify relevant tasks.
---

<!-- Tip: Use /create-skill in chat to generate content with agent assistance -->

Define the functionality provided by this skill, including detailed instructions and examples
---
name: spec-kit-one-shot-prep
description: Create Spec Kit preparation artifacts in one pass for TenantPilot/TenantAtlas features: spec.md, plan.md, and tasks.md. Use for feature ideas, roadmap items, spec candidates, governance/platform improvements, UX improvements, cleanup candidates, and repo-based preparation before manual analysis or implementation. This skill must not implement application code.
---

# Skill: Spec Kit One-Shot Preparation

## Purpose

Use this skill to create a complete Spec Kit preparation package for a new TenantPilot/TenantAtlas feature in one pass:

1. `spec.md`
2. `plan.md`
3. `tasks.md`

This skill prepares implementation work, but it must not perform implementation.

The intended workflow is:

```text
feature idea / roadmap item / spec candidate
→ one-shot spec + plan + tasks preparation
→ manual repo-based analysis/review
→ explicit implementation step later
```

## When to Use

Use this skill when the user asks to create or prepare Spec Kit artifacts from:

- a feature idea
- a spec candidate
- a roadmap item
- a product or UX requirement
- a governance/platform improvement
- an architecture cleanup candidate
- a refactoring preparation request
- a TenantPilot/TenantAtlas implementation idea that should first become a formal spec

Typical user prompts:

```text
Mach daraus spec, plan und tasks in einem Rutsch.
```

```text
Erstelle daraus eine neue Spec Kit Vorbereitung, aber noch nicht implementieren.
```

```text
Nimm diesen spec candidate und bereite spec/plan/tasks vor.
```

```text
Erzeuge die Spec Kit Artefakte, danach mache ich die Analyse manuell.
```

## Hard Rules

- Work strictly repo-based.
- 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 expand scope beyond the provided feature idea.
- Do not invent architecture that conflicts with repository truth.
- Do not create broad platform rewrites when a smaller implementable spec is possible.
- Prefer small, reviewable, implementation-ready specs.
- Preserve TenantPilot/TenantAtlas terminology.
- Follow the repository constitution and existing Spec Kit conventions.
- If repository truth conflicts with the user-provided draft, keep repository truth and document the deviation.
- If the feature is too broad, split it into one primary spec and optional follow-up spec candidates.

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

If the input is incomplete, proceed with the smallest reasonable interpretation and document assumptions. Do not block on clarification unless the request is impossible to scope safely.

## Required Repository Checks

Before creating or updating Spec Kit artifacts, inspect the relevant repository sources.

Always check:

1. `.specify/memory/constitution.md`
2. `.specify/templates/`
3. `specs/`
4. `docs/product/spec-candidates.md`
5. relevant roadmap documents under `docs/product/`
6. nearby existing specs with related terminology or scope

Check application code only as needed to avoid wrong naming, wrong architecture, or duplicate concepts. Do not edit application code.

## Spec Directory Rules

Create a new spec directory using the next valid spec number and a kebab-case slug:

```text
specs/<number>-<slug>/
```

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

Create or update only these preparation artifacts inside the selected spec directory:

```text
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. Do not create implementation files.

## `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 still must not implement.

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:

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

Use those distinctions only where relevant to the feature.

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

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

Prefer concrete tasks such as:

```text
- [ ] 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.

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

## Final Response Requirements

After creating or updating the artifacts, respond with:

1. Created or updated spec directory
2. Files created or updated
3. Important repo-based adjustments made
4. Assumptions made
5. Open questions, if any
6. Recommended next manual analysis prompt
7. Explicit statement that no implementation was performed

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

## Required Next Manual Analysis Prompt

Always provide a ready-to-copy prompt like this, adapted to the created spec number and slug:

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

Analysiere die neu erstellte Spec `<spec-number>-<slug>` 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.
```

## Example Invocation

User:

```text
Nimm diesen Spec Candidate und mach daraus spec, plan und tasks in einem Rutsch. Danach mache ich die Analyse manuell.
```

Expected behavior:

1. Inspect constitution, templates, specs, roadmap, and candidate docs.
2. Determine the next valid spec number.
3. Create `spec.md`, `plan.md`, and `tasks.md` in the new spec directory.
4. Keep scope tight.
5. Do not implement.
6. Return the summary and next manual analysis prompt.