Added Skill for Codex
This commit is contained in:
Ahmed Darrazi
parent
d3158f5103
commit
eb85b76eed
295
.codex/skills/browsertest/SKILL.md
Normal file
295
.codex/skills/browsertest/SKILL.md
Normal file
@ -0,0 +1,295 @@
|
|||||||
|
---
|
||||||
|
name: browsertest
|
||||||
|
description: Führe einen vollständigen Smoke-Browser-Test im Integrated Browser für das aktuelle Feature aus, inklusive Happy Path, zentraler Regressionen, Kontext-Prüfung und belastbarer Ergebniszusammenfassung.
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: GitHub Copilot
|
||||||
|
---
|
||||||
|
|
||||||
|
# Browser Smoke Test
|
||||||
|
|
||||||
|
## What This Skill Does
|
||||||
|
|
||||||
|
Use this skill to validate the current feature end-to-end in the integrated browser.
|
||||||
|
|
||||||
|
This is a focused smoke test, not a full exploratory test session. The goal is to prove that the primary operator flow:
|
||||||
|
|
||||||
|
- loads in the correct auth, workspace, and tenant context
|
||||||
|
- exposes the expected controls and decision points
|
||||||
|
- completes the main happy path without blocking issues
|
||||||
|
- lands in the expected end state or canonical drilldown
|
||||||
|
- does not show obvious regressions such as broken navigation, missing data, or conflicting actions
|
||||||
|
|
||||||
|
The skill should produce a concrete pass or fail result with actionable evidence.
|
||||||
|
|
||||||
|
## When To Apply
|
||||||
|
|
||||||
|
Activate this skill when:
|
||||||
|
|
||||||
|
- the user asks to smoke test the current feature in the browser
|
||||||
|
- a new Filament page, dashboard signal, report, wizard, or detail flow was just added
|
||||||
|
- a UI regression fix needs confirmation in a real browser context
|
||||||
|
- the primary question is whether the feature works from an operator perspective
|
||||||
|
- you need a quick integration-level check without writing a full browser test suite first
|
||||||
|
|
||||||
|
## What Success Looks Like
|
||||||
|
|
||||||
|
A successful smoke test confirms all of the following:
|
||||||
|
|
||||||
|
- the target route opens successfully
|
||||||
|
- the visible context is correct
|
||||||
|
- the main flow is usable
|
||||||
|
- the expected result appears after interaction
|
||||||
|
- the route or drilldown destination is correct
|
||||||
|
- the surface does not obviously violate its intended interaction model
|
||||||
|
|
||||||
|
If the test cannot be completed, the output must clearly state whether the blocker is:
|
||||||
|
|
||||||
|
- authentication
|
||||||
|
- missing data or fixture state
|
||||||
|
- routing
|
||||||
|
- UI interaction failure
|
||||||
|
- server error
|
||||||
|
- an unclear expected behavior contract
|
||||||
|
|
||||||
|
Do not guess. If the route or state is blocked, report the blocker explicitly.
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
|
||||||
|
Before running the browser smoke test, make sure you know:
|
||||||
|
|
||||||
|
- the canonical route or entry point for the feature
|
||||||
|
- the primary operator action or happy path
|
||||||
|
- the expected success state
|
||||||
|
- whether the feature depends on a specific tenant, workspace, or seeded record
|
||||||
|
|
||||||
|
When available, use the feature spec, quickstart, tasks, or current browser page as the source of truth.
|
||||||
|
|
||||||
|
## Standard Workflow
|
||||||
|
|
||||||
|
### 1. Define the smoke-test scope
|
||||||
|
|
||||||
|
Identify:
|
||||||
|
|
||||||
|
- the route to open
|
||||||
|
- the primary action to perform
|
||||||
|
- the expected end state
|
||||||
|
- one or two critical regressions that must not break
|
||||||
|
|
||||||
|
The smoke test should stay narrow. Prefer one complete happy path plus one critical boundary over broad exploratory clicking.
|
||||||
|
|
||||||
|
### 2. Establish the browser state
|
||||||
|
|
||||||
|
- Reuse the current browser page if it already matches the target feature.
|
||||||
|
- Otherwise open the canonical route.
|
||||||
|
- Confirm the current auth and scope context before interacting.
|
||||||
|
|
||||||
|
For this repo, that usually means checking whether the page is on:
|
||||||
|
|
||||||
|
- `/admin/...` for workspace-context surfaces
|
||||||
|
- `/admin/t/{tenant}/...` for tenant-context surfaces
|
||||||
|
|
||||||
|
### 3. Inspect before acting
|
||||||
|
|
||||||
|
- Use `read_page` before interacting so you understand the live controls, refs, headings, and route context.
|
||||||
|
- Prefer `read_page` over screenshots for actual interaction planning.
|
||||||
|
- Use screenshots only for visual evidence or when the user asks for them.
|
||||||
|
|
||||||
|
### 4. Execute the primary happy path
|
||||||
|
|
||||||
|
Run the smallest meaningful flow that proves the feature works.
|
||||||
|
|
||||||
|
Typical steps include:
|
||||||
|
|
||||||
|
- open the page
|
||||||
|
- verify heading or key summary text
|
||||||
|
- click the primary CTA or row
|
||||||
|
- fill the minimum required form fields
|
||||||
|
- confirm modal or dialog text when relevant
|
||||||
|
- submit or navigate
|
||||||
|
- verify the expected destination or changed state
|
||||||
|
|
||||||
|
After each meaningful action, re-read the page so the next step is based on current DOM state.
|
||||||
|
|
||||||
|
### 5. Validate the outcome
|
||||||
|
|
||||||
|
Check the exact result that matters for the feature.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- a new row appears
|
||||||
|
- a status changes
|
||||||
|
- a success message appears
|
||||||
|
- a report filter changes the result set
|
||||||
|
- a row click lands on the canonical detail page
|
||||||
|
- a dashboard signal links to the correct report page
|
||||||
|
|
||||||
|
### 6. Check for obvious regressions
|
||||||
|
|
||||||
|
Even in a smoke test, verify a few core non-negotiables:
|
||||||
|
|
||||||
|
- the page is not blank or half-rendered
|
||||||
|
- the main action is present and usable
|
||||||
|
- the visible context is correct
|
||||||
|
- the drilldown destination is canonical
|
||||||
|
- no obviously duplicated primary actions exist
|
||||||
|
- no stuck modal, spinner, or blocked interaction remains onscreen
|
||||||
|
|
||||||
|
### 7. Capture evidence and summarize clearly
|
||||||
|
|
||||||
|
Your result should state:
|
||||||
|
|
||||||
|
- route tested
|
||||||
|
- context used
|
||||||
|
- steps executed
|
||||||
|
- pass or fail
|
||||||
|
- exact blocker or discrepancy if failed
|
||||||
|
|
||||||
|
Include a screenshot only when it adds value.
|
||||||
|
|
||||||
|
## Tool Usage Guidance
|
||||||
|
|
||||||
|
Use the browser tools in this order by default:
|
||||||
|
|
||||||
|
1. `read_page`
|
||||||
|
2. `click_element`
|
||||||
|
3. `type_in_page`
|
||||||
|
4. `handle_dialog` when needed
|
||||||
|
5. `navigate_page` or `open_browser_page` only when route changes are required
|
||||||
|
6. `run_playwright_code` only if the normal browser tools are insufficient
|
||||||
|
7. `screenshot_page` for evidence, not for primary navigation logic
|
||||||
|
|
||||||
|
## Repo-Specific Guidance For TenantPilot
|
||||||
|
|
||||||
|
### Workspace surfaces
|
||||||
|
|
||||||
|
For `/admin` pages and similar workspace-context surfaces:
|
||||||
|
|
||||||
|
- verify the page is reachable without forcing tenant-route assumptions
|
||||||
|
- confirm any summary signal or CTA lands on the canonical destination
|
||||||
|
- verify calm-state versus attention-state behavior when the feature defines both
|
||||||
|
|
||||||
|
### Tenant surfaces
|
||||||
|
|
||||||
|
For `/admin/t/{tenant}/...` pages:
|
||||||
|
|
||||||
|
- verify the tenant context is explicit and correct
|
||||||
|
- verify drilldowns stay in the intended tenant scope
|
||||||
|
- treat cross-tenant leakage or silent scope changes as failures
|
||||||
|
|
||||||
|
### Filament list or report surfaces
|
||||||
|
|
||||||
|
For Filament tables, reports, or registry-style pages:
|
||||||
|
|
||||||
|
- verify the heading and table shell render
|
||||||
|
- verify fixed filters or summary controls exist when the spec requires them
|
||||||
|
- verify row click or the primary inspect affordance behaves as designed
|
||||||
|
- verify empty-state messaging is specific rather than generic when the feature defines custom behavior
|
||||||
|
|
||||||
|
### Filament detail pages
|
||||||
|
|
||||||
|
For detail or view surfaces:
|
||||||
|
|
||||||
|
- verify the canonical record loads
|
||||||
|
- verify expected sections or summary content are present
|
||||||
|
- verify critical actions or drillbacks are usable
|
||||||
|
|
||||||
|
## Result Format
|
||||||
|
|
||||||
|
Use a compact result format like this:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Browser smoke result: PASS
|
||||||
|
Route: /admin/findings/hygiene
|
||||||
|
Context: workspace member with visible hygiene issues
|
||||||
|
Steps: opened report -> verified filters -> clicked finding row -> landed on canonical finding detail
|
||||||
|
Verified: report rendered, primary interaction worked, drilldown route was correct
|
||||||
|
```
|
||||||
|
|
||||||
|
If the test fails:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Browser smoke result: FAIL
|
||||||
|
Route: /admin/findings/hygiene
|
||||||
|
Context: authenticated workspace member
|
||||||
|
Failed step: clicking the summary CTA
|
||||||
|
Expected: navigate to /admin/findings/hygiene
|
||||||
|
Actual: remained on /admin with no route change
|
||||||
|
Blocker: CTA appears rendered but is not interactive
|
||||||
|
```
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### Example 1: Smoke test a new report page
|
||||||
|
|
||||||
|
Use this when the feature adds a new read-only report.
|
||||||
|
|
||||||
|
Steps:
|
||||||
|
|
||||||
|
- open the canonical report route
|
||||||
|
- verify the page heading and main controls
|
||||||
|
- confirm the table or defined empty state is visible
|
||||||
|
- click one row or primary inspect affordance
|
||||||
|
- verify navigation lands on the canonical detail route
|
||||||
|
|
||||||
|
Pass criteria:
|
||||||
|
|
||||||
|
- report loads
|
||||||
|
- intended controls exist
|
||||||
|
- primary inspect path works
|
||||||
|
|
||||||
|
### Example 2: Smoke test a dashboard signal
|
||||||
|
|
||||||
|
Use this when the feature adds a summary signal on `/admin`.
|
||||||
|
|
||||||
|
Steps:
|
||||||
|
|
||||||
|
- open `/admin`
|
||||||
|
- find the signal
|
||||||
|
- verify the visible count or summary text
|
||||||
|
- click the CTA
|
||||||
|
- confirm navigation lands on the canonical downstream surface
|
||||||
|
|
||||||
|
Pass criteria:
|
||||||
|
|
||||||
|
- signal is visible in the correct state
|
||||||
|
- CTA text is present
|
||||||
|
- CTA opens the correct route
|
||||||
|
|
||||||
|
### Example 3: Smoke test a tenant detail follow-up
|
||||||
|
|
||||||
|
Use this when a workspace-level surface should drill into a tenant-level detail page.
|
||||||
|
|
||||||
|
Steps:
|
||||||
|
|
||||||
|
- open the workspace-level surface
|
||||||
|
- trigger the drilldown
|
||||||
|
- verify the target route includes the correct tenant and record
|
||||||
|
- confirm the target page actually loads the expected detail content
|
||||||
|
|
||||||
|
Pass criteria:
|
||||||
|
|
||||||
|
- drilldown route is canonical
|
||||||
|
- tenant context is correct
|
||||||
|
- destination content matches the selected record
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
- Clicking before reading the page state and refs
|
||||||
|
- Treating a blocked auth session as a feature failure
|
||||||
|
- Confusing workspace-context routes with tenant-context routes
|
||||||
|
- Reporting visual impressions without validating the actual interaction result
|
||||||
|
- Forgetting to re-read the page after a modal opens or a route changes
|
||||||
|
- Claiming success without verifying the final destination or changed state
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
This skill does not replace:
|
||||||
|
|
||||||
|
- full exploratory QA
|
||||||
|
- formal Pest browser coverage
|
||||||
|
- accessibility review
|
||||||
|
- visual regression approval
|
||||||
|
- backend correctness tests
|
||||||
|
|
||||||
|
It is a fast, real-browser confidence pass for the current feature.
|
||||||
8
.codex/skills/giteaflow/SKILL.md
Normal file
8
.codex/skills/giteaflow/SKILL.md
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
---
|
||||||
|
name: giteaflow
|
||||||
|
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 -->
|
||||||
|
|
||||||
|
comit all changes, push to remote, and create a pull request against platform-dev with gitea mcp
|
||||||
167
.codex/skills/pest-testing/SKILL.md
Normal file
167
.codex/skills/pest-testing/SKILL.md
Normal file
@ -0,0 +1,167 @@
|
|||||||
|
---
|
||||||
|
name: pest-testing
|
||||||
|
description: "Tests applications using the Pest 4 PHP framework. Activates when writing tests, creating unit or feature tests, adding assertions, testing Livewire components, browser testing, debugging test failures, working with datasets or mocking; or when the user mentions test, spec, TDD, expects, assertion, coverage, or needs to verify functionality works."
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: laravel
|
||||||
|
---
|
||||||
|
|
||||||
|
# Pest Testing 4
|
||||||
|
|
||||||
|
## When to Apply
|
||||||
|
|
||||||
|
Activate this skill when:
|
||||||
|
|
||||||
|
- Creating new tests (unit, feature, or browser)
|
||||||
|
- Modifying existing tests
|
||||||
|
- Debugging test failures
|
||||||
|
- Working with browser testing or smoke testing
|
||||||
|
- Writing architecture tests or visual regression tests
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
Use `search-docs` for detailed Pest 4 patterns and documentation.
|
||||||
|
|
||||||
|
## Basic Usage
|
||||||
|
|
||||||
|
### Creating Tests
|
||||||
|
|
||||||
|
All tests must be written using Pest. Use `php artisan make:test --pest {name}`.
|
||||||
|
|
||||||
|
### Test Organization
|
||||||
|
|
||||||
|
- Unit/Feature tests: `tests/Feature` and `tests/Unit` directories.
|
||||||
|
- Browser tests: `tests/Browser/` directory.
|
||||||
|
- Do NOT remove tests without approval - these are core application code.
|
||||||
|
|
||||||
|
### Basic Test Structure
|
||||||
|
|
||||||
|
<!-- Basic Pest Test Example -->
|
||||||
|
```php
|
||||||
|
it('is true', function () {
|
||||||
|
expect(true)->toBeTrue();
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running Tests
|
||||||
|
|
||||||
|
- Run minimal tests with filter before finalizing: `php artisan test --compact --filter=testName`.
|
||||||
|
- Run all tests: `php artisan test --compact`.
|
||||||
|
- Run file: `php artisan test --compact tests/Feature/ExampleTest.php`.
|
||||||
|
|
||||||
|
## Assertions
|
||||||
|
|
||||||
|
Use specific assertions (`assertSuccessful()`, `assertNotFound()`) instead of `assertStatus()`:
|
||||||
|
|
||||||
|
<!-- Pest Response Assertion -->
|
||||||
|
```php
|
||||||
|
it('returns all', function () {
|
||||||
|
$this->postJson('/api/docs', [])->assertSuccessful();
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
| Use | Instead of |
|
||||||
|
|-----|------------|
|
||||||
|
| `assertSuccessful()` | `assertStatus(200)` |
|
||||||
|
| `assertNotFound()` | `assertStatus(404)` |
|
||||||
|
| `assertForbidden()` | `assertStatus(403)` |
|
||||||
|
|
||||||
|
## Mocking
|
||||||
|
|
||||||
|
Import mock function before use: `use function Pest\Laravel\mock;`
|
||||||
|
|
||||||
|
## Datasets
|
||||||
|
|
||||||
|
Use datasets for repetitive tests (validation rules, etc.):
|
||||||
|
|
||||||
|
<!-- Pest Dataset Example -->
|
||||||
|
```php
|
||||||
|
it('has emails', function (string $email) {
|
||||||
|
expect($email)->not->toBeEmpty();
|
||||||
|
})->with([
|
||||||
|
'james' => 'james@laravel.com',
|
||||||
|
'taylor' => 'taylor@laravel.com',
|
||||||
|
]);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pest 4 Features
|
||||||
|
|
||||||
|
| Feature | Purpose |
|
||||||
|
|---------|---------|
|
||||||
|
| Browser Testing | Full integration tests in real browsers |
|
||||||
|
| Smoke Testing | Validate multiple pages quickly |
|
||||||
|
| Visual Regression | Compare screenshots for visual changes |
|
||||||
|
| Test Sharding | Parallel CI runs |
|
||||||
|
| Architecture Testing | Enforce code conventions |
|
||||||
|
|
||||||
|
### Browser Test Example
|
||||||
|
|
||||||
|
Browser tests run in real browsers for full integration testing:
|
||||||
|
|
||||||
|
- Browser tests live in `tests/Browser/`.
|
||||||
|
- Use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories.
|
||||||
|
- Use `RefreshDatabase` for clean state per test.
|
||||||
|
- Interact with page: click, type, scroll, select, submit, drag-and-drop, touch gestures.
|
||||||
|
- Test on multiple browsers (Chrome, Firefox, Safari) if requested.
|
||||||
|
- Test on different devices/viewports (iPhone 14 Pro, tablets) if requested.
|
||||||
|
- Switch color schemes (light/dark mode) when appropriate.
|
||||||
|
- Take screenshots or pause tests for debugging.
|
||||||
|
|
||||||
|
<!-- Pest Browser Test Example -->
|
||||||
|
```php
|
||||||
|
it('may reset the password', function () {
|
||||||
|
Notification::fake();
|
||||||
|
|
||||||
|
$this->actingAs(User::factory()->create());
|
||||||
|
|
||||||
|
$page = visit('/sign-in');
|
||||||
|
|
||||||
|
$page->assertSee('Sign In')
|
||||||
|
->assertNoJavaScriptErrors()
|
||||||
|
->click('Forgot Password?')
|
||||||
|
->fill('email', 'nuno@laravel.com')
|
||||||
|
->click('Send Reset Link')
|
||||||
|
->assertSee('We have emailed your password reset link!');
|
||||||
|
|
||||||
|
Notification::assertSent(ResetPassword::class);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Smoke Testing
|
||||||
|
|
||||||
|
Quickly validate multiple pages have no JavaScript errors:
|
||||||
|
|
||||||
|
<!-- Pest Smoke Testing Example -->
|
||||||
|
```php
|
||||||
|
$pages = visit(['/', '/about', '/contact']);
|
||||||
|
|
||||||
|
$pages->assertNoJavaScriptErrors()->assertNoConsoleLogs();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Visual Regression Testing
|
||||||
|
|
||||||
|
Capture and compare screenshots to detect visual changes.
|
||||||
|
|
||||||
|
### Test Sharding
|
||||||
|
|
||||||
|
Split tests across parallel processes for faster CI runs.
|
||||||
|
|
||||||
|
### Architecture Testing
|
||||||
|
|
||||||
|
Pest 4 includes architecture testing (from Pest 3):
|
||||||
|
|
||||||
|
<!-- Architecture Test Example -->
|
||||||
|
```php
|
||||||
|
arch('controllers')
|
||||||
|
->expect('App\Http\Controllers')
|
||||||
|
->toExtendNothing()
|
||||||
|
->toHaveSuffix('Controller');
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
- Not importing `use function Pest\Laravel\mock;` before using mock
|
||||||
|
- Using `assertStatus(200)` instead of `assertSuccessful()`
|
||||||
|
- Forgetting datasets for repetitive validation tests
|
||||||
|
- Deleting tests without approval
|
||||||
|
- Forgetting `assertNoJavaScriptErrors()` in browser tests
|
||||||
625
.codex/skills/platform-feature-finish/SKILL.md
Normal file
625
.codex/skills/platform-feature-finish/SKILL.md
Normal file
@ -0,0 +1,625 @@
|
|||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
name: platform-feature-finish
|
||||||
|
description: Commit, push, create a Gitea PR from a TenantPilot platform feature branch into platform-dev, and optionally refresh the platform-dev to dev integration PR by rebase.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: platform-feature-finish
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Automate the TenantPilot platform feature completion workflow.
|
||||||
|
|
||||||
|
Trigger this skill when the user says something like:
|
||||||
|
|
||||||
|
- "alles committen pushen und PR gegen platform-dev"
|
||||||
|
- "feature fertig, bitte PR erstellen"
|
||||||
|
- "platform feature abschließen"
|
||||||
|
- "commit push PR mit Gitea MCP"
|
||||||
|
- "mach PR gegen platform-dev"
|
||||||
|
- "finish platform feature"
|
||||||
|
- "platform-dev nach dev vorbereiten"
|
||||||
|
- "platform-dev PR aktualisieren"
|
||||||
|
- "out-of-date mit dev beheben"
|
||||||
|
- "integration PR refresh"
|
||||||
|
- "platform-dev auf dev rebasen"
|
||||||
|
|
||||||
|
This skill handles:
|
||||||
|
|
||||||
|
1. Validate current Git branch
|
||||||
|
2. Commit all feature changes
|
||||||
|
3. Push current feature branch
|
||||||
|
4. Create a Gitea pull request into `platform-dev`
|
||||||
|
5. Refresh the `platform-dev` → `dev` integration PR when explicitly requested
|
||||||
|
6. Report the PR link and next integration step
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Branch Model
|
||||||
|
|
||||||
|
TenantPilot uses area branches:
|
||||||
|
|
||||||
|
```text
|
||||||
|
dev = shared integration branch
|
||||||
|
platform-dev = platform/application area integration branch
|
||||||
|
website-dev = website/marketing area integration branch
|
||||||
|
```
|
||||||
|
|
||||||
|
For platform features:
|
||||||
|
|
||||||
|
```text
|
||||||
|
platform-dev
|
||||||
|
↓
|
||||||
|
feature branch
|
||||||
|
↓
|
||||||
|
PR back to platform-dev
|
||||||
|
↓
|
||||||
|
platform-dev → dev integration PR
|
||||||
|
```
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
|
||||||
|
- Platform feature branches MUST target `platform-dev`.
|
||||||
|
- Do NOT target `dev` directly unless the user explicitly asks.
|
||||||
|
- Do NOT use `website-dev` for platform features.
|
||||||
|
- `platform-dev` is the default PR base for TenantPilot platform/application work.
|
||||||
|
- `dev` is the shared integration branch.
|
||||||
|
|
||||||
|
### Solo Workflow Rule
|
||||||
|
|
||||||
|
The user works alone on `platform-dev`.
|
||||||
|
|
||||||
|
For refreshing the integration branch before opening or updating the PR `platform-dev` → `dev`, prefer rebase over merge.
|
||||||
|
|
||||||
|
Do not repeatedly merge `origin/dev` into `platform-dev` for refresh.
|
||||||
|
|
||||||
|
Avoid creating repeated merge commits like:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Merge remote-tracking branch 'origin/dev' into platform-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `--force-with-lease`, never plain `--force`.
|
||||||
|
|
||||||
|
If rebase conflicts occur, stop and report the conflict files.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
|
||||||
|
Before committing:
|
||||||
|
|
||||||
|
1. Confirm repository root.
|
||||||
|
2. Confirm current branch is not protected.
|
||||||
|
|
||||||
|
Protected branches:
|
||||||
|
|
||||||
|
```text
|
||||||
|
dev
|
||||||
|
platform-dev
|
||||||
|
website-dev
|
||||||
|
main
|
||||||
|
master
|
||||||
|
```
|
||||||
|
|
||||||
|
If the current branch is protected, STOP and report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Ich bin auf einem geschützten Branch. Bitte zuerst einen Feature-Branch auschecken.
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Confirm remote exists.
|
||||||
|
4. Confirm there are local changes, untracked files, or unpushed commits.
|
||||||
|
5. Confirm there are no unresolved conflicts.
|
||||||
|
|
||||||
|
Do not ask for confirmation unless:
|
||||||
|
|
||||||
|
- The current branch is protected.
|
||||||
|
- Git status indicates unresolved conflicts.
|
||||||
|
- There is no remote configured.
|
||||||
|
- `.env` or other local secret/config files would be committed.
|
||||||
|
- Commit fails.
|
||||||
|
- Push fails.
|
||||||
|
- Gitea MCP PR creation fails.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Required Tools
|
||||||
|
|
||||||
|
Use terminal for Git operations.
|
||||||
|
|
||||||
|
Use Gitea MCP for pull request creation.
|
||||||
|
|
||||||
|
Preferred Gitea MCP operation:
|
||||||
|
|
||||||
|
```text
|
||||||
|
create_pull_request
|
||||||
|
```
|
||||||
|
|
||||||
|
Required PR parameters:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"owner": "ahmido",
|
||||||
|
"repo": "TenantAtlas",
|
||||||
|
"head": "<current-feature-branch>",
|
||||||
|
"base": "platform-dev",
|
||||||
|
"title": "<generated-title>",
|
||||||
|
"body": "<generated-body>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### Step 1 — Inspect Git state
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git rev-parse --show-toplevel
|
||||||
|
git rev-parse --abbrev-ref HEAD
|
||||||
|
git status --porcelain
|
||||||
|
git status -sb
|
||||||
|
git config --get remote.origin.url
|
||||||
|
git log --oneline --max-count=5
|
||||||
|
```
|
||||||
|
|
||||||
|
Determine:
|
||||||
|
|
||||||
|
- repository root
|
||||||
|
- current branch
|
||||||
|
- changed files
|
||||||
|
- untracked files
|
||||||
|
- remote URL
|
||||||
|
- whether there are unpushed commits
|
||||||
|
- whether unresolved conflicts exist
|
||||||
|
|
||||||
|
If the current branch is protected, stop.
|
||||||
|
|
||||||
|
If unresolved conflicts exist, stop.
|
||||||
|
|
||||||
|
If no remote exists, stop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 2 — Check for local environment files
|
||||||
|
|
||||||
|
Before `git add -A`, check whether local environment/config files are modified or untracked:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git status --porcelain | grep -E '(^.. \.env$|^.. apps/platform/\.env$|^.. .*\.env$)' || true
|
||||||
|
```
|
||||||
|
|
||||||
|
If `.env` or another environment file is included, STOP and report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Achtung: Eine .env-/Environment-Datei ist geändert oder untracked. Ich committe das nicht automatisch. Bitte prüfen oder aus dem Commit entfernen.
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not commit secrets or local runtime configuration.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 3 — Build commit message
|
||||||
|
|
||||||
|
Use the current branch name.
|
||||||
|
|
||||||
|
If branch starts with a spec number, for example:
|
||||||
|
|
||||||
|
```text
|
||||||
|
256-external-support-desk-handoff
|
||||||
|
```
|
||||||
|
|
||||||
|
Generate:
|
||||||
|
|
||||||
|
```text
|
||||||
|
feat(specs/256): external support desk handoff
|
||||||
|
```
|
||||||
|
|
||||||
|
If branch does not contain a spec number, generate:
|
||||||
|
|
||||||
|
```text
|
||||||
|
feat(platform): complete <branch-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
|
||||||
|
- Use lowercase subject.
|
||||||
|
- Use feature-style subject.
|
||||||
|
- Do not include `WIP`.
|
||||||
|
- Do not include `final`.
|
||||||
|
- Do not include overly generic `updates`.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
```text
|
||||||
|
feat(specs/256): external support desk handoff
|
||||||
|
feat(specs/252): platform localization v1
|
||||||
|
feat(platform): improve tenant review workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 4 — Commit all changes
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -A
|
||||||
|
git commit -m "<commit-message>"
|
||||||
|
```
|
||||||
|
|
||||||
|
If there are no local changes to commit, continue only if the branch has unpushed commits.
|
||||||
|
|
||||||
|
Check unpushed commits with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git status -sb
|
||||||
|
git log --oneline origin/<current-branch>..HEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
If there are no local changes and no unpushed commits, report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Es gibt keine lokalen Änderungen und keine unpushed commits. Ich erstelle keinen leeren Commit.
|
||||||
|
```
|
||||||
|
|
||||||
|
Then continue to PR creation only if the branch already exists remotely or can be pushed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 5 — Push branch
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git push --set-upstream origin <current-branch>
|
||||||
|
```
|
||||||
|
|
||||||
|
If the upstream already exists, this is acceptable.
|
||||||
|
|
||||||
|
Never force-push unless the user explicitly requests it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 6 — Create PR into platform-dev via Gitea MCP
|
||||||
|
|
||||||
|
Use Gitea MCP to create a pull request:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"owner": "ahmido",
|
||||||
|
"repo": "TenantAtlas",
|
||||||
|
"head": "<current-feature-branch>",
|
||||||
|
"base": "platform-dev",
|
||||||
|
"title": "<commit-message>",
|
||||||
|
"body": "Implements platform feature branch `<current-feature-branch>`.\n\nTarget branch: `platform-dev`.\n\nFollow-up integration path after merge:\n\n`platform-dev` → `dev`."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If a PR already exists for the same branch and base, do not create a duplicate.
|
||||||
|
|
||||||
|
Report the existing PR if available.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional Step — Check platform-dev to dev PR
|
||||||
|
|
||||||
|
After creating the feature PR, check whether an open integration PR exists:
|
||||||
|
|
||||||
|
```text
|
||||||
|
platform-dev → dev
|
||||||
|
```
|
||||||
|
|
||||||
|
If a Gitea MCP list/search pull request function is available, use it.
|
||||||
|
|
||||||
|
If one exists, report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Der Folge-PR `platform-dev` → `dev` existiert bereits: <url>
|
||||||
|
```
|
||||||
|
|
||||||
|
If none exists, report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Nach dem Merge dieses Feature-PRs sollte der Integrations-PR `platform-dev` → `dev` erstellt oder aktualisiert werden.
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not automatically create the `platform-dev` → `dev` PR unless the user explicitly asks for it.
|
||||||
|
|
||||||
|
Reason: before the feature PR is merged into `platform-dev`, the integration PR may not include the new feature yet.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration Refresh Mode
|
||||||
|
|
||||||
|
Use this mode when the user explicitly says one of the following:
|
||||||
|
|
||||||
|
- "platform-dev nach dev vorbereiten"
|
||||||
|
- "platform-dev PR aktualisieren"
|
||||||
|
- "out-of-date mit dev beheben"
|
||||||
|
- "integration PR refresh"
|
||||||
|
- "platform-dev auf dev rebasen"
|
||||||
|
- "auch platform-dev nach dev"
|
||||||
|
- "und danach platform-dev nach dev"
|
||||||
|
- "full integration"
|
||||||
|
- "kompletten platform-dev zu dev PR machen"
|
||||||
|
- "folge-pr erstellen"
|
||||||
|
|
||||||
|
This mode prepares or updates the integration PR:
|
||||||
|
|
||||||
|
```text
|
||||||
|
platform-dev → dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Because the user works alone on `platform-dev`, prefer rebase over merge.
|
||||||
|
|
||||||
|
### Integration Refresh Preconditions
|
||||||
|
|
||||||
|
Before running this mode:
|
||||||
|
|
||||||
|
1. Ensure the working tree is clean.
|
||||||
|
2. Ensure there are no unresolved conflicts.
|
||||||
|
3. Fetch remote branches.
|
||||||
|
4. Ensure `origin/platform-dev` exists.
|
||||||
|
5. Ensure `origin/dev` exists.
|
||||||
|
|
||||||
|
If the working tree is dirty, STOP and report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Der Working Tree ist nicht sauber. Bitte erst Änderungen committen, stashen oder verwerfen, bevor `platform-dev` auf `dev` rebased wird.
|
||||||
|
```
|
||||||
|
|
||||||
|
If unresolved conflicts exist, STOP and report the conflict files.
|
||||||
|
|
||||||
|
### Integration Refresh Workflow
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch origin
|
||||||
|
git checkout platform-dev
|
||||||
|
git reset --hard origin/platform-dev
|
||||||
|
git rebase origin/dev
|
||||||
|
git push --force-with-lease origin platform-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
After pushing, verify that `origin/dev` is now an ancestor of `origin/platform-dev`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch origin
|
||||||
|
git merge-base --is-ancestor origin/dev origin/platform-dev \
|
||||||
|
&& echo "OK: platform-dev contains dev" \
|
||||||
|
|| echo "OUTDATED: platform-dev does not contain dev"
|
||||||
|
```
|
||||||
|
|
||||||
|
If the verification prints `OUTDATED`, stop and report it. Do not claim the PR is up-to-date.
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
|
||||||
|
- Do not merge `origin/dev` into `platform-dev` for this refresh.
|
||||||
|
- Do not create repeated merge commits from `origin/dev` into `platform-dev`.
|
||||||
|
- Use `git push --force-with-lease origin platform-dev` after a successful rebase.
|
||||||
|
- Never use plain `git push --force`.
|
||||||
|
- If `git rebase origin/dev` reports conflicts, stop immediately.
|
||||||
|
- Do not continue to PR creation while a rebase is unresolved.
|
||||||
|
- Do not auto-merge the PR.
|
||||||
|
- Do not claim Gitea will remove the out-of-date warning unless the ancestor check succeeds.
|
||||||
|
|
||||||
|
If rebase conflicts occur, report:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Rebase-Konflikte erkannt. Ich habe gestoppt.
|
||||||
|
|
||||||
|
Konfliktdateien:
|
||||||
|
<files>
|
||||||
|
|
||||||
|
Bitte Konflikte lösen, dann `git rebase --continue` ausführen oder den Rebase mit `git rebase --abort` abbrechen.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create or Report Integration PR
|
||||||
|
|
||||||
|
After the rebase, push, and ancestor verification succeeded, use Gitea MCP to create or report the integration PR:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"owner": "ahmido",
|
||||||
|
"repo": "TenantAtlas",
|
||||||
|
"head": "platform-dev",
|
||||||
|
"base": "dev",
|
||||||
|
"title": "chore(platform): merge platform-dev into dev",
|
||||||
|
"body": "Integrates latest TenantPilot platform changes from `platform-dev` into `dev`.\n\nThis PR was created by agent on user request; do not merge automatically."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If an open PR already exists for `platform-dev` → `dev`, do not create a duplicate. Report the existing PR.
|
||||||
|
|
||||||
|
### Integration Refresh Reporting Format
|
||||||
|
|
||||||
|
Final response for this mode must include:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Fertig.
|
||||||
|
|
||||||
|
- Branch aktualisiert: platform-dev
|
||||||
|
- Refresh-Methode: rebase auf origin/dev
|
||||||
|
- Ancestor-Check: origin/dev ist Ancestor von origin/platform-dev
|
||||||
|
- Push: --force-with-lease origin/platform-dev
|
||||||
|
- Integration PR: <url>
|
||||||
|
- Base: dev
|
||||||
|
- Hinweis: PR wurde nicht automatisch gemerged.
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not claim tests passed unless they were actually executed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reporting Format
|
||||||
|
|
||||||
|
Final response must be concise and include:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Fertig.
|
||||||
|
|
||||||
|
- Branch: <branch>
|
||||||
|
- Commit: <commit-sha or "keine neuen Änderungen">
|
||||||
|
- Push: origin/<branch>
|
||||||
|
- PR: <url>
|
||||||
|
- Base: platform-dev
|
||||||
|
- Nächster Schritt: Nach Merge `platform-dev` → `dev` PR aktualisieren/erstellen
|
||||||
|
```
|
||||||
|
|
||||||
|
If tests were not run, say:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Tests wurden in diesem Skill nicht automatisch ausgeführt.
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not claim tests passed unless the tool actually ran them.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Safety Rules
|
||||||
|
|
||||||
|
- Never commit directly to `dev`, `platform-dev`, `website-dev`, `main`, or `master`.
|
||||||
|
- Never force-push unless explicitly requested.
|
||||||
|
- For Integration Refresh Mode only, `git push --force-with-lease origin platform-dev` is allowed because the user works alone on `platform-dev`; never use plain `--force`.
|
||||||
|
- Never auto-merge PRs unless explicitly requested.
|
||||||
|
- Never target `dev` directly for platform feature PRs unless explicitly requested.
|
||||||
|
- Never delete branches unless explicitly requested.
|
||||||
|
- Never claim tests were run unless the tool actually ran them.
|
||||||
|
- Never commit `.env`, secrets, local tokens, local mock-server configuration, or temporary runtime-only changes.
|
||||||
|
- If migrations were created, mention that the target environment needs migration execution after deployment.
|
||||||
|
- If unresolved conflicts exist, stop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Useful Commands
|
||||||
|
|
||||||
|
Inspect:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git rev-parse --show-toplevel
|
||||||
|
git rev-parse --abbrev-ref HEAD
|
||||||
|
git status --porcelain
|
||||||
|
git status -sb
|
||||||
|
git config --get remote.origin.url
|
||||||
|
```
|
||||||
|
|
||||||
|
Detect protected branch:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
branch="$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
case "$branch" in
|
||||||
|
dev|platform-dev|website-dev|main|master)
|
||||||
|
echo "PROTECTED_BRANCH:$branch"
|
||||||
|
exit 2
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
```
|
||||||
|
|
||||||
|
Detect unresolved conflicts:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --name-only --diff-filter=U
|
||||||
|
```
|
||||||
|
|
||||||
|
Detect `.env` changes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git status --porcelain | grep -E '(^.. \.env$|^.. apps/platform/\.env$|^.. .*\.env$)' || true
|
||||||
|
```
|
||||||
|
|
||||||
|
Commit:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -A
|
||||||
|
git commit -m "<message>"
|
||||||
|
```
|
||||||
|
|
||||||
|
Push:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git push --set-upstream origin "$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
```
|
||||||
|
|
||||||
|
Latest commit:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git rev-parse --short HEAD
|
||||||
|
git log -1 --pretty=%s
|
||||||
|
```
|
||||||
|
|
||||||
|
Integration refresh:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch origin
|
||||||
|
git checkout platform-dev
|
||||||
|
git reset --hard origin/platform-dev
|
||||||
|
git rebase origin/dev
|
||||||
|
git push --force-with-lease origin platform-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify integration refresh:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch origin
|
||||||
|
git merge-base --is-ancestor origin/dev origin/platform-dev \
|
||||||
|
&& echo "OK: platform-dev contains dev" \
|
||||||
|
|| echo "OUTDATED: platform-dev does not contain dev"
|
||||||
|
```
|
||||||
|
|
||||||
|
Check rebase conflicts:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --name-only --diff-filter=U
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example User Request
|
||||||
|
|
||||||
|
User:
|
||||||
|
|
||||||
|
```text
|
||||||
|
alles committen pushen und pr gegen platform-dev mit gitea mcp
|
||||||
|
```
|
||||||
|
|
||||||
|
Assistant should:
|
||||||
|
|
||||||
|
1. Check current branch.
|
||||||
|
2. Stop if branch is protected.
|
||||||
|
3. Stop if `.env` or secrets would be committed.
|
||||||
|
4. Commit all changes.
|
||||||
|
5. Push current branch.
|
||||||
|
6. Create PR into `platform-dev` with Gitea MCP.
|
||||||
|
7. Report result.
|
||||||
|
|
||||||
|
Do not ask unnecessary follow-up questions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Integration Refresh Request
|
||||||
|
|
||||||
|
User:
|
||||||
|
|
||||||
|
```text
|
||||||
|
platform-dev PR aktualisieren
|
||||||
|
```
|
||||||
|
|
||||||
|
Assistant should:
|
||||||
|
|
||||||
|
1. Ensure the working tree is clean.
|
||||||
|
2. Fetch origin.
|
||||||
|
3. Checkout `platform-dev`.
|
||||||
|
4. Reset local `platform-dev` to `origin/platform-dev`.
|
||||||
|
5. Rebase `platform-dev` onto `origin/dev`.
|
||||||
|
6. Push with `--force-with-lease`.
|
||||||
|
7. Verify `origin/dev` is an ancestor of `origin/platform-dev`.
|
||||||
|
8. Create or report the PR `platform-dev` → `dev`.
|
||||||
|
9. Report result.
|
||||||
|
|
||||||
|
Do not merge the PR automatically.
|
||||||
447
.codex/skills/spec-kit-implementation-loop/SKILL.md
Normal file
447
.codex/skills/spec-kit-implementation-loop/SKILL.md
Normal file
@ -0,0 +1,447 @@
|
|||||||
|
---
|
||||||
|
name: spec-kit-implementation-loop
|
||||||
|
description: Implement an existing TenantPilot/TenantAtlas Spec Kit feature, run tests, browser smoke checks where applicable, post-implementation analysis, fix all confirmed in-scope findings when safe and bounded, and repeat until no in-scope findings remain or a stop condition is reached.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: Spec Kit Implementation Loop
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Use this skill to implement an already prepared TenantPilot/TenantAtlas Spec Kit feature and verify it with a bounded implementation loop.
|
||||||
|
|
||||||
|
This skill assumes `spec.md`, `plan.md`, and `tasks.md` already exist and have passed preparation readiness or have been explicitly accepted by the user.
|
||||||
|
|
||||||
|
The intended workflow is:
|
||||||
|
|
||||||
|
```text
|
||||||
|
active or explicitly named spec
|
||||||
|
→ inspect repo truth, constitution, spec, plan, tasks, and relevant code/tests
|
||||||
|
→ evaluate implementation gates
|
||||||
|
→ implement strictly task-by-task
|
||||||
|
→ 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 + browser smoke + analysis + fix loop until clean or bounded stop condition is reached
|
||||||
|
→ final implementation report
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
Use this skill when the user asks to:
|
||||||
|
|
||||||
|
- implement an active or explicitly named Spec Kit feature
|
||||||
|
- run Spec Kit implement
|
||||||
|
- analyze after implementation
|
||||||
|
- fix implementation findings
|
||||||
|
- repeat implementation verification until no confirmed in-scope findings remain
|
||||||
|
- run tests and browser smoke checks after implementation
|
||||||
|
|
||||||
|
Typical user prompts:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implementiere die aktive Spec und analysiere danach, ob alles passt.
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implementiere specs/243-product-usage-adoption-telemetry streng nach tasks.md.
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
Mach Spec Kit implement und danach analyse. Behebe alle Abweichungen und wiederhole bis sauber.
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implementiere die vorbereitete Spec. Danach Tests, Browser Smoke Test falls UI betroffen ist, Analyse und Fix-Loop bis keine In-Scope Findings mehr offen sind.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Hard Rules
|
||||||
|
|
||||||
|
- Work strictly repo-based.
|
||||||
|
- Implement only the active or explicitly named Spec Kit feature.
|
||||||
|
- Do not choose a new candidate.
|
||||||
|
- Do not create a new spec.
|
||||||
|
- Do not expand scope beyond `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 patches over broad rewrites.
|
||||||
|
- Treat repository truth as authoritative over assumptions.
|
||||||
|
- 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, browser smoke 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 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:
|
||||||
|
|
||||||
|
- explicit spec directory such as `specs/<number>-<slug>/`
|
||||||
|
- instruction to use the current active Spec Kit feature
|
||||||
|
- instruction to implement the prepared/current spec
|
||||||
|
|
||||||
|
If 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:
|
||||||
|
|
||||||
|
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 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 changes for this operation, continue cautiously.
|
||||||
|
5. Do not force checkout, reset, stash, rebase, merge, or delete branches.
|
||||||
|
6. Do not overwrite unrelated work.
|
||||||
|
|
||||||
|
## Quality Gates
|
||||||
|
|
||||||
|
### Gate 1: Spec Readiness Gate
|
||||||
|
|
||||||
|
Required before implementation starts.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
- Stop before implementation.
|
||||||
|
- Report readiness gaps.
|
||||||
|
- Do not compensate for an unclear spec by inventing implementation scope.
|
||||||
|
|
||||||
|
### Gate 2: 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 3: 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 4: 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 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 5: 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 6: 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, browser smoke result, 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.
|
||||||
|
|
||||||
|
## Implementation Loop
|
||||||
|
|
||||||
|
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 task-by-task.
|
||||||
|
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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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 an 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 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
|
||||||
|
|
||||||
|
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 Prompt
|
||||||
|
|
||||||
|
Provide a ready-to-copy prompt like this, adapted to the active spec number and slug:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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 Invocation
|
||||||
|
|
||||||
|
User:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Nutze den Skill spec-kit-implementation-loop.
|
||||||
|
Implementiere die aktive Spec.
|
||||||
|
Danach Tests ausführen, Browser Smoke Test falls UI/user-facing betroffen ist, Post-Implementation Analyse durchführen und alle bestätigten In-Scope Findings unabhängig von Severity beheben, wenn safe und bounded.
|
||||||
|
Wiederhole test + browser smoke + analysis + fix bis keine In-Scope Findings mehr offen sind oder eine Stop Condition greift.
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
```
|
||||||
612
.codex/skills/spec-kit-next-best-prep/SKILL.md
Normal file
612
.codex/skills/spec-kit-next-best-prep/SKILL.md
Normal file
@ -0,0 +1,612 @@
|
|||||||
|
---
|
||||||
|
name: spec-kit-next-best-prep
|
||||||
|
description: Select the next suitable TenantPilot/TenantAtlas spec candidate from roadmap/spec-candidates, run the repository's Spec Kit preparation flow, create or update spec.md/plan.md/tasks.md, run preparation analysis, fix preparation-artifact issues only, and stop before application implementation.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: Spec Kit Next-Best Preparation
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Use this skill to prepare the next implementation-ready Spec Kit package for TenantPilot/TenantAtlas without implementing application code.
|
||||||
|
|
||||||
|
This skill supports preparation only:
|
||||||
|
|
||||||
|
1. Select or scope the next suitable feature from roadmap/spec-candidates.
|
||||||
|
2. Run the repository's real Spec Kit preparation workflow where available.
|
||||||
|
3. Create or update `spec.md`, `plan.md`, and `tasks.md`.
|
||||||
|
4. Run preparation `analyze` when supported.
|
||||||
|
5. Fix preparation-artifact issues only.
|
||||||
|
6. Evaluate preparation quality gates.
|
||||||
|
7. Stop before application implementation.
|
||||||
|
|
||||||
|
The intended workflow is:
|
||||||
|
|
||||||
|
```text
|
||||||
|
roadmap / spec-candidates / feature idea
|
||||||
|
→ inspect repo truth, constitution, roadmap, spec candidates, existing specs, and relevant code
|
||||||
|
→ select the next suitable candidate or scope the provided idea
|
||||||
|
→ run Spec Kit specify/plan/tasks/analyze where available
|
||||||
|
→ create or update spec.md + plan.md + tasks.md
|
||||||
|
→ fix preparation-artifact issues only
|
||||||
|
→ evaluate Candidate Selection Gate and Spec Readiness Gate
|
||||||
|
→ final preparation report
|
||||||
|
→ explicit implementation step later
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
Use this skill when the user asks to:
|
||||||
|
|
||||||
|
- select the next best spec candidate from `docs/product/spec-candidates.md` and roadmap sources
|
||||||
|
- turn a feature idea, roadmap item, or candidate into `spec.md`, `plan.md`, and `tasks.md`
|
||||||
|
- prepare Spec Kit artifacts in one pass
|
||||||
|
- run specify/plan/tasks/analyze without implementation
|
||||||
|
- fix preparation analysis issues in Spec Kit artifacts only
|
||||||
|
- prepare a feature package for a later implementation skill
|
||||||
|
|
||||||
|
Typical user prompts:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Nimm den nächsten sinnvollen Spec Candidate aus Roadmap/spec-candidates und mach spec, plan und tasks.
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
Mach daraus spec, plan und tasks in einem Rutsch, aber noch nicht implementieren.
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
Wähle aus roadmap.md und spec-candidates.md die nächste sinnvollste Spec und führe specify, plan, tasks und analyze aus.
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
Behebe alle analyze-Issues in den Spec-Kit-Artefakten. Keine Application-Implementierung.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Hard Rules
|
||||||
|
|
||||||
|
- Work strictly repo-based.
|
||||||
|
- This is a preparation-only skill.
|
||||||
|
- Do not implement application code.
|
||||||
|
- Do not modify production code.
|
||||||
|
- Do not modify migrations, models, services, jobs, Filament resources, Livewire components, policies, commands, routes, views, tests, or runtime behavior.
|
||||||
|
- Use the repository's actual Spec Kit workflow, scripts, templates, branch naming rules, and generated paths when available.
|
||||||
|
- 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.
|
||||||
|
- Create or update only Spec Kit preparation artifacts unless repository conventions require additional documentation artifacts.
|
||||||
|
- 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 over broad rewrites.
|
||||||
|
- Treat repository truth as authoritative over assumptions.
|
||||||
|
- If repository truth conflicts with the user-provided draft or candidate wording, keep repository truth and document the deviation.
|
||||||
|
- Fix only confirmed preparation-artifact findings from Spec Kit preparation analysis.
|
||||||
|
- Do not leave preparation findings open silently. If they are not fixed, document exactly why.
|
||||||
|
- Do not run destructive commands.
|
||||||
|
- Do not force checkout, reset, stash, rebase, merge, or delete branches.
|
||||||
|
- Do not overwrite existing specs.
|
||||||
|
- Do not rewrite completed specs back into preparation state.
|
||||||
|
- Do not remove or normalize implementation history, close-out notes, validation results, completed task markers, smoke results, or post-implementation review language from completed specs.
|
||||||
|
- Treat completed-spec close-out and validation language as intentional repository history, not preparation drift.
|
||||||
|
- Do not move from preparation to an implementation step inside this skill.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
- 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 no suitable candidate can be selected safely, stop and report why.
|
||||||
|
|
||||||
|
## Required Repository Checks
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
Do not edit application code.
|
||||||
|
|
||||||
|
## Completed-Spec Guardrail
|
||||||
|
|
||||||
|
Before selecting an existing spec package as a `next-best-prep` target, explicitly check whether the spec is already completed, implementation-closed, or validated.
|
||||||
|
|
||||||
|
A spec must be treated as completed if any of the following signals are present in `spec.md`, `plan.md`, `tasks.md`, `quickstart.md`, checklist artifacts, or related Spec Kit package files:
|
||||||
|
|
||||||
|
- `Implementation Close-Out`
|
||||||
|
- `Implementation completed on`
|
||||||
|
- `Implementation Validation Results`
|
||||||
|
- `Implemented and validated`
|
||||||
|
- `Review Outcome` or `Implementation Review Outcome`
|
||||||
|
- passed validation, smoke, browser, or guardrail results
|
||||||
|
- completed task checklist markers for the implementation tasks
|
||||||
|
- post-implementation review or close-out language
|
||||||
|
- a status marker indicating implemented, completed, closed, or validated
|
||||||
|
|
||||||
|
If a spec is completed:
|
||||||
|
|
||||||
|
- exclude it from `next-best-prep` candidate selection
|
||||||
|
- do not patch, normalize, rewrite, or convert it back to preparation-only state
|
||||||
|
- do not remove close-out sections, validation results, completed task markers, smoke results, or post-implementation review language
|
||||||
|
- treat those artifacts as historical implementation evidence
|
||||||
|
- only use the completed spec as context for dependency or roadmap reasoning
|
||||||
|
|
||||||
|
If all high-priority candidates are already specced, active, or completed, stop and report `no safe next prep target` instead of modifying existing completed specs.
|
||||||
|
|
||||||
|
## Git and Branch Safety
|
||||||
|
|
||||||
|
Before running any Spec Kit command:
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Quality Gates
|
||||||
|
|
||||||
|
### 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 target is not a completed spec package with implementation close-out, validation results, completed tasks, smoke results, or post-implementation review history.
|
||||||
|
- 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.
|
||||||
|
- If the only plausible targets are completed specs, stop and report `no safe next prep target`; do not modify those completed specs.
|
||||||
|
- Do not invent a new roadmap direction to force progress.
|
||||||
|
|
||||||
|
### Gate 2: Spec Readiness Gate
|
||||||
|
|
||||||
|
Required before reporting that the package is ready for implementation.
|
||||||
|
|
||||||
|
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 in a later implementation skill.
|
||||||
|
- Required checklist artifacts exist when the constitution requires them.
|
||||||
|
|
||||||
|
Fail behavior:
|
||||||
|
|
||||||
|
- Fix preparation-artifact issues when they are safe and bounded.
|
||||||
|
- If readiness cannot be achieved without implementation or unresolved product decisions, stop and report the gap.
|
||||||
|
- Do not compensate for an unclear spec by inventing implementation scope.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
- Check existing specs for completed-spec signals before selecting an existing package as a refresh target.
|
||||||
|
- Exclude completed specs from next-best-prep selection, even if their artifacts contain close-out, validation, or completed-task language that would look like drift in a preparation-only package.
|
||||||
|
- 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?
|
||||||
|
8. **Completion Safety**: Is the target genuinely unprepared or incomplete, rather than an already completed spec whose historical close-out artifacts should be preserved?
|
||||||
|
|
||||||
|
## 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
|
||||||
|
- completed-spec check result for related existing specs
|
||||||
|
- 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
|
||||||
|
|
||||||
|
### 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 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
|
||||||
|
|
||||||
|
Do not use analyze as a trigger to implement application code.
|
||||||
|
|
||||||
|
### Step 6: Fix preparation-artifact issues only
|
||||||
|
|
||||||
|
If preparation analyze finds issues, first confirm that the selected package is not completed. Then fix only Spec Kit preparation artifacts such as:
|
||||||
|
|
||||||
|
- `spec.md`
|
||||||
|
- `plan.md`
|
||||||
|
- `tasks.md`
|
||||||
|
- `checklists/requirements.md` or other 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
|
||||||
|
- add missing checklist artifacts required by the constitution
|
||||||
|
|
||||||
|
Forbidden fixes include:
|
||||||
|
|
||||||
|
- modifying application code
|
||||||
|
- creating migrations
|
||||||
|
- editing models, services, jobs, policies, Filament resources, Livewire components, tests, commands, routes, or views
|
||||||
|
- running implementation or test-fix loops
|
||||||
|
- changing runtime behavior
|
||||||
|
- removing implementation close-out history from completed specs
|
||||||
|
- converting completed specs back to preparation-only wording
|
||||||
|
- changing passed validation or smoke results into planned validation commands
|
||||||
|
- unchecking completed implementation tasks in a completed spec
|
||||||
|
|
||||||
|
### Step 7: Evaluate the Spec Readiness Gate
|
||||||
|
|
||||||
|
After preparation analyze has passed or preparation-artifact issues have been fixed, evaluate the Spec Readiness Gate.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```text
|
||||||
|
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:
|
||||||
|
|
||||||
|
```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.
|
||||||
|
|
||||||
|
## `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:
|
||||||
|
|
||||||
|
```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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
## Failure Handling
|
||||||
|
|
||||||
|
If a Spec Kit command or preparation analyze phase fails:
|
||||||
|
|
||||||
|
1. Stop at the relevant gate.
|
||||||
|
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.
|
||||||
|
|
||||||
|
If a completed spec is accidentally selected or modified:
|
||||||
|
|
||||||
|
1. Stop immediately.
|
||||||
|
2. Report that the selected spec is completed and therefore not a valid preparation target.
|
||||||
|
3. Revert only the changes made by this operation to that completed spec package, if they are isolated and safe to revert.
|
||||||
|
4. Run `git status --short` and report remaining changes.
|
||||||
|
5. Re-run candidate selection excluding completed specs.
|
||||||
|
6. If no safe unprepared candidate exists, report `no safe next prep target`.
|
||||||
|
|
||||||
|
## Final Response Requirements
|
||||||
|
|
||||||
|
Respond with:
|
||||||
|
|
||||||
|
1. Selected candidate and why it was chosen
|
||||||
|
2. Why close alternatives were deferred
|
||||||
|
3. Completed-spec guardrail result for related existing specs
|
||||||
|
4. Current branch after Spec Kit execution, if changed
|
||||||
|
5. Generated spec path
|
||||||
|
6. Files created or updated by Spec Kit
|
||||||
|
7. Preparation analyze result summary
|
||||||
|
8. Preparation-artifact fixes applied after analyze
|
||||||
|
9. Assumptions made
|
||||||
|
10. Open questions, if any
|
||||||
|
11. Candidate Selection Gate result
|
||||||
|
12. Spec Readiness Gate result
|
||||||
|
13. Recommended next implementation prompt
|
||||||
|
14. Explicit statement that no application implementation was performed
|
||||||
|
|
||||||
|
Keep the final response concise, but include enough detail for the user to continue immediately.
|
||||||
|
|
||||||
|
## Manual Review and Next-Step Prompts
|
||||||
|
|
||||||
|
Provide a ready-to-copy manual artifact review prompt like this, adapted to the generated spec branch/path:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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.
|
||||||
|
```
|
||||||
|
|
||||||
|
Also provide a ready-to-copy implementation prompt for the separate implementation skill after analyze has passed or preparation-artifact issues have been fixed:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
/spec-kit-implementation-loop
|
||||||
|
|
||||||
|
Implementiere die vorbereitete Spec `<spec-branch-or-spec-path>` streng anhand von `tasks.md`.
|
||||||
|
|
||||||
|
Danach Tests ausführen, Browser Smoke Test falls UI/user-facing betroffen ist, Post-Implementation Analyse durchführen und alle bestätigten In-Scope Findings unabhängig von Severity beheben, wenn safe und bounded.
|
||||||
|
|
||||||
|
Wiederhole test + browser smoke + analysis + fix bis keine In-Scope Findings mehr offen sind oder eine Stop Condition greift.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example Invocation
|
||||||
|
|
||||||
|
User:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Nutze den Skill spec-kit-next-best-prep.
|
||||||
|
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. Exclude already completed specs from preparation or refresh targets, preserving their close-out and validation history.
|
||||||
|
6. Evaluate the Candidate Selection Gate.
|
||||||
|
7. Run the repository's real Spec Kit `specify` flow, letting it handle branch/spec setup.
|
||||||
|
8. Run the repository's real Spec Kit `plan` flow.
|
||||||
|
9. Run the repository's real Spec Kit `tasks` flow.
|
||||||
|
10. Run the repository's real Spec Kit preparation `analyze` flow.
|
||||||
|
11. Fix analyze issues only in Spec Kit preparation artifacts.
|
||||||
|
12. Evaluate the Spec Readiness Gate.
|
||||||
|
13. Stop before application implementation.
|
||||||
|
14. Return selection rationale, branch/path summary, artifact summary, analyze summary, fixes applied, gates, and next implementation prompt.
|
||||||
|
```
|
||||||
129
.codex/skills/tailwindcss-development/SKILL.md
Normal file
129
.codex/skills/tailwindcss-development/SKILL.md
Normal file
@ -0,0 +1,129 @@
|
|||||||
|
---
|
||||||
|
name: tailwindcss-development
|
||||||
|
description: "Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes."
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: laravel
|
||||||
|
---
|
||||||
|
|
||||||
|
# Tailwind CSS Development
|
||||||
|
|
||||||
|
## When to Apply
|
||||||
|
|
||||||
|
Activate this skill when:
|
||||||
|
|
||||||
|
- Adding styles to components or pages
|
||||||
|
- Working with responsive design
|
||||||
|
- Implementing dark mode
|
||||||
|
- Extracting repeated patterns into components
|
||||||
|
- Debugging spacing or layout issues
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
Use `search-docs` for detailed Tailwind CSS v4 patterns and documentation.
|
||||||
|
|
||||||
|
## Basic Usage
|
||||||
|
|
||||||
|
- Use Tailwind CSS classes to style HTML. Check and follow existing Tailwind conventions in the project before introducing new patterns.
|
||||||
|
- Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue).
|
||||||
|
- Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically.
|
||||||
|
|
||||||
|
## Tailwind CSS v4 Specifics
|
||||||
|
|
||||||
|
- Always use Tailwind CSS v4 and avoid deprecated utilities.
|
||||||
|
- `corePlugins` is not supported in Tailwind v4.
|
||||||
|
|
||||||
|
### CSS-First Configuration
|
||||||
|
|
||||||
|
In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed:
|
||||||
|
|
||||||
|
<!-- CSS-First Config -->
|
||||||
|
```css
|
||||||
|
@theme {
|
||||||
|
--color-brand: oklch(0.72 0.11 178);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Import Syntax
|
||||||
|
|
||||||
|
In Tailwind v4, import Tailwind with a regular CSS `@import` statement instead of the `@tailwind` directives used in v3:
|
||||||
|
|
||||||
|
<!-- v4 Import Syntax -->
|
||||||
|
```diff
|
||||||
|
- @tailwind base;
|
||||||
|
- @tailwind components;
|
||||||
|
- @tailwind utilities;
|
||||||
|
+ @import "tailwindcss";
|
||||||
|
```
|
||||||
|
|
||||||
|
### Replaced Utilities
|
||||||
|
|
||||||
|
Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric.
|
||||||
|
|
||||||
|
| Deprecated | Replacement |
|
||||||
|
|------------|-------------|
|
||||||
|
| bg-opacity-* | bg-black/* |
|
||||||
|
| text-opacity-* | text-black/* |
|
||||||
|
| border-opacity-* | border-black/* |
|
||||||
|
| divide-opacity-* | divide-black/* |
|
||||||
|
| ring-opacity-* | ring-black/* |
|
||||||
|
| placeholder-opacity-* | placeholder-black/* |
|
||||||
|
| flex-shrink-* | shrink-* |
|
||||||
|
| flex-grow-* | grow-* |
|
||||||
|
| overflow-ellipsis | text-ellipsis |
|
||||||
|
| decoration-slice | box-decoration-slice |
|
||||||
|
| decoration-clone | box-decoration-clone |
|
||||||
|
|
||||||
|
## Spacing
|
||||||
|
|
||||||
|
Use `gap` utilities instead of margins for spacing between siblings:
|
||||||
|
|
||||||
|
<!-- Gap Utilities -->
|
||||||
|
```html
|
||||||
|
<div class="flex gap-8">
|
||||||
|
<div>Item 1</div>
|
||||||
|
<div>Item 2</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dark Mode
|
||||||
|
|
||||||
|
If existing pages and components support dark mode, new pages and components must support it the same way, typically using the `dark:` variant:
|
||||||
|
|
||||||
|
<!-- Dark Mode -->
|
||||||
|
```html
|
||||||
|
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
|
||||||
|
Content adapts to color scheme
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
### Flexbox Layout
|
||||||
|
|
||||||
|
<!-- Flexbox Layout -->
|
||||||
|
```html
|
||||||
|
<div class="flex items-center justify-between gap-4">
|
||||||
|
<div>Left content</div>
|
||||||
|
<div>Right content</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Grid Layout
|
||||||
|
|
||||||
|
<!-- Grid Layout -->
|
||||||
|
```html
|
||||||
|
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
|
||||||
|
<div>Card 1</div>
|
||||||
|
<div>Card 2</div>
|
||||||
|
<div>Card 3</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
- Using deprecated v3 utilities (bg-opacity-*, flex-shrink-*, etc.)
|
||||||
|
- Using `@tailwind` directives instead of `@import "tailwindcss"`
|
||||||
|
- Trying to use `tailwind.config.js` instead of CSS `@theme` directive
|
||||||
|
- Using margins for spacing between siblings instead of gap utilities
|
||||||
|
- Forgetting to add dark mode variants when the project uses dark mode
|
||||||
Loading…
Reference in New Issue
Block a user