Contract
- Input: repository with
CONTEXT.md, ADRs, source code, and automated baseline. - Output: one Markdown report under
.reports/and one JSON artifact under.reports/, both with layered findings and a prompt for the user. - Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.
- Rule: documented standards override defaults; explicit project rules take precedence.
- Rule: if blocked by missing context or dependencies, surface the blocker before proceeding.
Provenance
| Question | Answer |
|---|---|
| What is the source of truth? | The user's request, originating spec/issue, and the skill's declared outputs |
| What is in scope? | Work covered by the skill's acceptance criteria and completion rules |
| What is explicitly out of scope? | Files, behaviors, and decisions outside the skill's declared boundary |
| Who or what consumes this artifact afterward? | The next skill in the workflow or the user |
| What evidence proves it is done? | Completion criteria met, structured result returned, validation passed |
| What risk remains? | Subjective judgment calls, missing context, or external dependency failures |
Load-bearing rules
- Do not proceed without explicit user direction.
- Do not write a report that fails the gate.
- Do not merge or rerank across axes.
- Do not abort the workflow; continue with reduced confidence and mark affected findings accordingly.
Completion
- the skill's completion criteria are explicitly checked
- the structured result is returned and validated
- any blockers or skipped validations are documented
- the next consumer is identified or the work is handed off
Artifact
Return ProjectViabilityArtifact as structured output in the current response. Do not write local artifact files unless the user explicitly asks for an export.
Repository evidence
Use code-review findings as repository evidence when assessing viability. Preserve their severity, confidence, location, and limitations; do not convert an unverified risk into a project-blocking conclusion without independent support.
Project Viability
Analyze whether the project is viable, functional, and scalable across logic, architecture, technical capacity, team maintainability, and domain growth. Ground every finding in CONTEXT.md, the ADRs under docs/adr/, and actual code evidence. Complement subjective findings with an automated baseline of objective health signals.
Three parallel sub-agents evaluate each dimension independently so findings do not pollute each other's context. This skill aggregates their outputs into a single Markdown report and a structured JSON artifact.
Confidence Criteria
Use these criteria when assigning confidence levels to findings:
- High: ≥2 independent citations supporting the finding, or 1 citation with automated baseline confirmation.
- Medium: 1 citation with no automated confirmation, or 2 weak citations.
- Low: No direct citation; finding is an inference from structure or naming alone.
Findings with Low confidence must be flagged explicitly and must not drive Not viable or Broken ratings alone.
Numeric Scoring
In addition to categorical ratings, assign a numeric score 1–5 per dimension:
- 5 — Excellent, no material concerns
- 4 — Good, minor improvements possible
- 3 — Adequate, at least one material concern
- 2 — Poor, multiple material concerns
- 1 — Critical, project is blocked or fundamentally broken
Numeric scores enable tracking across assessments. Include both categorical rating and numeric score in the executive summary.
Steps
1. Pre-flight check
Before proceeding, verify the following in the repository:
CONTEXT.mdexists and is non-empty. If missing, note "Insufficient context" for viability and record the gap.docs/adr/exists. If missing, note that ADR-grounded evaluation is limited and record the gap.references/evaluation-criteria.md,references/report-template.md,references/subagent-prompts.md, andreferences/health-baseline.mdexist. If missing, warn and use inline defaults.
Record any gaps in the pre-flight findings. Do not abort the workflow; continue with reduced confidence and mark affected findings accordingly.
2. Gather context
Read CONTEXT.md and all files under docs/adr/. If CONTEXT-MAP.md exists, read it and resolve each mapped context. Record the domain vocabulary, stated goals, constraints, and recorded decisions.
3. Map the codebase
Identify the project shape: interactive app, batch pipeline, agentic system, library, backend service, or hybrid. Map the top-level structure, entry points, data flow, and external integrations. Note any seams between layers. Record approximate LOC and module count.
4. Automated baseline
Run the checks in references/health-baseline.md. Record the following objective signals:
- Repository LOC and module count
- Dependency health (outdated, vulnerable, orphaned)
- Test coverage signal (test LOC ratio, CI presence)
- Cross-import signal (import count across module boundaries)
- Configuration drift signal (uncommitted config, IaC changes without ADR)
Pass the baseline results to all sub-agents as part of the shared context.
5. Spawn parallel sub-agents
Send a single message with three Agent tool calls using the general-purpose subagent type. Use the prompt templates in references/subagent-prompts.md. Include:
- The shared context gathered in steps 1, 2, 3, and 4.
- The viability brief.
- The functionality brief.
- The scalability brief.
Each sub-agent returns:
- A categorical rating.
- A numeric score (1–5).
- Evidence list with citations.
- Confidence level per finding (High / Medium / Low).
- Risk level per finding (High / Medium / Low) based on Likelihood × Impact.
- Conditions, missing items, or limiting factors as applicable.
6. Quality gate
Before aggregating, verify:
- Every finding cites
CONTEXT.md, an ADR path, or a concrete code location. - Ratings are internally consistent (e.g., "Not viable" must have at least one blocker).
- No dimension contradicts another without an explicit unresolved conflict noted.
- Confidence levels are assigned to all findings.
- Risk levels are assigned to all findings.
- Numeric scores are consistent with categorical ratings.
If the quality gate fails, iterate on the failing sub-agent output before aggregation. Do not write a report that fails the gate.
7. Aggregate findings
Combine the three sub-agent outputs into a single report using the structure in references/report-template.md. Preserve each dimension's findings separately; do not merge or rerank across axes.
8. Write the report
Write the aggregated findings to .reports/<YYYYMMDD>-viability.md. Keep the report under 2000 words. Include:
- Executive summary with the three categorical ratings and three numeric scores.
- Evidence-backed findings per layer with confidence and risk levels.
- Priority matrix (Impact × Effort) for recommendations.
- Validation notes documenting quality gate results.
- Pre-flight gaps, if any.
- Delta section comparing with previous assessment, if one exists.
9. Write the JSON artifact
Write the structured JSON artifact to .reports/<YYYYMMDD>-viability.json. The artifact must include:
repositoryanddatepreflightgapsbaselinesignalsdimensionswith categorical rating, numeric score, findings, and recommendations per dimensionoverallposture and conflict resolutionvalidationnotesdeltafrom previous assessment, if one exists
10. Ask the user what to do
After writing the reports, present the path forward and ask the user to choose:
- Address the top findings via
/implementor/codebase-design. - Sharpen the project model via
/grill-with-docsor/domain-modeling. - Revisit ADRs via
/docs-management. - Abandon or pause the assessment.
Do not proceed without explicit user direction.
Resources
references/evaluation-criteria.md
Read this file when scoring viability, functionality, and scalability. It defines the rating thresholds, evidence requirements, anti-patterns, confidence criteria, numeric scoring, risk matrix, and conflict resolution rules for each dimension.
references/report-template.md
Use this template when writing the .reports/<YYYYMMDD>-viability.md file. It specifies the required sections, wording conventions, validation note format, and JSON artifact schema.
references/subagent-prompts.md
Use these prompts when spawning the three parallel sub-agents in step 5. Each prompt includes the shared context and a focused brief for one dimension, with an output schema that includes rating, numeric score, confidence, and risk.
references/health-baseline.md
Read this file before step 4. It defines the automated baseline checks to run, the signals to collect, and how to pass them to sub-agents.
references/edge-cases.md
Read this file when the repository deviates from the standard shape (missing CONTEXT.md, monorepos, legacy projects, config-only repos, dependency health issues).
references/integration-points.md
Read this file after writing the report to decide which follow-up skill to recommend. It maps dimension ratings to the most effective next action, considering numeric scores and risk levels.
@include .agents/skills/platform/contract-base.xml