Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-adopt
saas-adopt
UnverifiedBrownfield audit of existing SaaS docs and code with a numbered Studio migration plan.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.3 KB |
| references/1-detect.md | markdown | 3.8 KB |
| references/2-format-audit.md | markdown | 9.9 KB |
| references/3-classify.md | markdown | 1.3 KB |
| references/4-migration-plan.md | markdown | 2.8 KB |
| references/5-summary.md | markdown | 2.5 KB |
| references/6-write.md | markdown | 3.5 KB |
| references/7-first-action.md | markdown | 3.3 KB |
references/2-format-audit.md
View on GitHub# /saas-adopt — Phase 2: Format Audit
> Part of `/saas-adopt`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 2: Format Audit
**In this file:**
- 2a: PRD Format Audit
- 2b: ADR Format Audit
- 2c: features-modules-index.md Format Audit
- 2d: Story Format Audit
- 2e: Infrastructure Audit
- 2f: Project Config Audit
- 2g: v1.0 Migration Check
For each artifact type in scope (based on argument mode **and the resolved
workflow tier**), check not just that the file exists but that it contains the
internal structure the template requires. At `minimal`, scope the audit to
`design/product-brief.md` — do not audit for PRDs, ADRs, or UX specs (they are not expected).
Steps 2e (the Stack reference row only), 2f (project config) and 2g (v1.0
migration check) run at every tier.
### 2a: PRD Format Audit
**Gather section presence deterministically — do not read the PRDs to count
headings.** For each PRD discovered in Phase 1, pass its path explicitly to the
structure-check script:
```
Bash: bash .claude/scripts/prd-structure-check.sh [path-to-prd]
```
**Pass paths one at a time; do not invoke it bare.** The no-argument form sweeps
`design/prd/` only, and a brownfield project's PRDs are not guaranteed to live
there — pass whatever paths Phase 1 found. The script prints a `PRESENT:` list
and, when applicable, an `ABSENT:` list per file. It reports **presence only**
and makes no REQUIRED/ADVISORY judgment (that is the tier logic below), and it
already accepts `## Detailed Design` as satisfying the `Detailed Rules`
requirement, so do not flag that alias as missing.
If the script prints `Not found:` for a path or errors, that is a **discovery
failure, not a format gap** — report it as "could not audit [path]" and do not
count it as a missing-sections finding.
**Then apply the workflow tier** resolved above to each file's PRESENT/ABSENT
lists. Which sections are **required** (a miss = gap) vs **advisory** (a miss =
informational):
- **`full`** — all 8 sections are required.
- **`standard`** — the 5 required (Problem Statement, Requirements Pool / Functional Requirements, Edge Cases,
Dependencies, Acceptance Criteria) + Data Models / Schema and Business Rules for any system that defines
data structures, rates, or quotas; User Personas and Configuration Options are advisory.
- **`minimal`** — PRDs are not expected; audit `design/product-brief.md` instead,
against `.claude/docs/templates/product-brief.md`: each of the six required fields
present and not a placeholder; the three one-liners advisory. Any PRD that
does exist is checked at the `standard` bar, advisorily.
The script's 8 canonical labels are: Problem Statement, Success Metrics, User Stories,
Requirements Pool, Data Models / Schema, Security & Permissions, Edge Cases, Acceptance Criteria.
A section reported PRESENT can still be an empty heading. For each PRD, also
record with a targeted grep (not a full read):
- Placeholder-only sections — the script's `PLACEHOLDER:` line names the
present sections that hold only `[To be designed]` or nothing; a
single-line stub body is the same in effect, so spot-check short sections.
- The `**Status**:` header field — `Grep pattern="^>?[[:space:]]*\*\*Status\*\*:"`.
Valid values: `Draft`, `In Design`, `Designed`, `In Review`, `Approved`,
`Implemented`, `Needs Revision`.
> **The `>?` is load-bearing, and so are `Draft`/`Implemented`.** Both emitters
> write this field inside a blockquote — `.claude/docs/templates/prd-template.md`
> and `/saas-design-system` produce `> **Status**: …` — so an anchor of
> `^\*\*Status\*\*:` matches nothing and reports *every* template-compliant PRD
> as missing its Status. The template's own value list offers `Draft` and
> `Implemented`, so both must count as valid.
### 2b: ADR Format Audit
For each ADR file found, check for these critical sections:
| Section | Impact if missing |
|---|---|
| `## Status` | **BLOCKING** — `/saas-story-readiness` ADR status check silently passes everything |
| `## ADR Dependencies` | HIGH — dependency ordering in `/saas-architecture-review` breaks |
| `## Engine Compatibility` | HIGH — post-cutoff API risk is unknown |
| `## PRD Requirements Addressed` | MEDIUM — traceability matrix loses coverage |
| `## Performance Implications` | LOW — not pipeline-critical |
For each ADR, record: which sections present, which missing, current Status value
if the Status section exists.
### 2c: features-modules-index.md Format Audit
If `design/prd/features-modules-index.md` exists:
1. **Parenthetical status values** — Grep for any Status cell containing
parentheses: `"Needs Revision ("`, `"In Progress ("`, etc.
These break exact-string matching in `/saas-gate-check`, `/saas-create-stories`,
and `/saas-architecture-review`. **BLOCKING.**
2. **Valid status values** — check that Status column values are only from:
`Not Started`, `In Progress`, `In Review`, `Designed`, `Approved`, `Needs Revision`
Flag any unrecognised values.
3. **Column structure** — check that the table has at minimum: System name,
Layer, Priority, Status columns. Missing columns degrade skill functionality.
### 2d: Story Format Audit
For each story file found:
- **`Manifest Version:` field** — present in story header? (LOW — auto-passes if absent)
- **TR-ID reference** — does story contain `TR-[a-z]+-[0-9]+` pattern? (MEDIUM — no staleness tracking)
- **ADR reference** — does story reference at least one ADR? (check for `ADR-` pattern)
- **Status field** — present and readable?
- **Acceptance criteria** — does the story have a checkbox list (`- [ ]`)?
### 2e: Infrastructure Audit
| Artifact | Path | Impact if missing |
|---|---|---|
| TR registry | `docs/architecture/tr-registry.yaml` | HIGH — no stable requirement IDs |
| Control manifest | `docs/architecture/control-manifest.md` | HIGH — no layer rules for stories |
| Manifest version stamp | In manifest header: `Manifest Version:` | MEDIUM — staleness checks blind |
| Sprint status | `production/sprint-status.yaml` | MEDIUM — `/saas-sprint-status` falls back to markdown |
| Stage file | `project.stage` in `project.yaml` (fallback `production/stage.txt`) | MEDIUM — phase auto-detect unreliable |
| Stack reference | `docs/engine-reference/[engine]/VERSION.md` | HIGH — ADR engine checks blind |
| Architecture traceability | `docs/architecture/requirements-traceability.md` | MEDIUM — no persistent matrix |
At `workflow: minimal` only the Stack reference row applies. The TR registry,
control manifest and its version stamp, sprint status, stage file and
traceability matrix are not on the minimal path, so their absence is not a gap.
### 2f: Project Config Audit
Read `project.yaml` (the primary config store) and `.claude/docs/technical-preferences.md` (legacy mirror). A setting counts as configured if EITHER source has a real value (in technical-preferences.md, `[TO BE CONFIGURED]` means unconfigured):
- `stack.frontend`/`version`/`language` (else the Stack/Language fields) → HIGH if unconfigured in both (ADR skills fail)
- `naming.*` (else Naming conventions) → MEDIUM
- `performance.*` (else Performance budgets) → MEDIUM
- Forbidden Patterns, Allowed Libraries (technical-preferences.md only — not migrated to project.yaml) → LOW (starts empty by design)
### 2g: v1.0 Migration Check
A project is a **v1.0 project needing migration** when `project.yaml` does NOT
exist at the repo root AND at least one legacy file does: `production/stage.txt`,
`production/review-mode.txt`, or a `.claude/docs/technical-preferences.md` with
real values.
"Real values" means one of the keys the converter actually migrates — Stack,
Language, the naming, platform and performance fields,
Framework, or the specialists. Not merely "some bullet is filled in": the
shipped template ships one prose default (`- **Required Tests**: …`) that is
never migrated, and counting it would make every fresh clone read as a v1.0
project.
Do not hand-migrate. Run the converter, which is deterministic and covered by
the framework's own test suite:
```bash
bash .claude/scripts/migrate-v1-config.sh --dry-run
```
The dry run writes nothing; record what it lists for the report. Do not run the
converter during the audit — Phase 2 reads silently. The migration is
classified BLOCKING in Phase 3, heads the plan, and **Phase 7 offers it as the
first action**: report what the dry run listed, then ask "May I run the
converter? It writes `project.yaml` and `production/migration-report.md`." If
the user approves, run it without `--dry-run`. It
writes `project.yaml` plus `production/migration-report.md` and **deletes
nothing** — the whole operation stays reversible with `git checkout`.
Then tell the user to read `production/migration-report.md` before running:
```bash
bash .claude/scripts/migrate-v1-config.sh --finalize
```
`--finalize` deletes a legacy file only after proving its value is present in
`project.yaml`; on mismatch it deletes nothing and exits 4. It never deletes
`technical-preferences.md`, which still holds Forbidden Patterns and Allowed
Libraries.
**If the script refuses with exit 3**, do not work around it. Exit 3 means one
of two things, and the message says which:
- **the values DISAGREE** — two sources of truth and no way to know which the
user edited last. Surface it and let them decide.
- **a `production/migration-report.md` is already present** — a migration ran
here, so these are post-migration leftovers and `--finalize` is the next step,
not a second `migrate`.
Both files merely *existing* is not exit 3 and must not be reported as a
conflict: `/saas-start` writes `production/stage.txt` on every new v1.1 project as a
mirror, so agreement is the normal state. The script says
`the legacy files mirror it (values agree)` and exits 0 for that.
Classify as **BLOCKING** in Phase 3: until migration runs, every skill reads
config through the legacy fallback chain, and v1.1 settings are unavailable.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |