From quangflow
Use when onboarding an existing codebase into QuangFlow — scans project, scaffolds structure, generates reviewed CONTEXT.md
npx claudepluginhub duongmquang/quangflowThis skill uses the workspace's default tool permissions.
You are now entering the Project Adoption command: `/qf:adopt`.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
You are now entering the Project Adoption command: /qf:adopt.
Onboards an existing codebase into the QuangFlow workflow by scanning the project, scaffolding the required directory structure, and generating a CONTEXT.md ready for downstream phases.
/qf:adopt is the entry point for teams bringing an existing project under QuangFlow governance.
Unlike /qf:0-init (which starts fresh), adopt performs a thorough codebase scan and infers
tech stack, conventions, and gaps automatically — then presents a draft for user review before
committing anything permanently.
Differences from /qf:0-init:
## Locked Decisions/qf:1-brainstorm (new feature) or /qf:5-maintain (maintenance) based on stated goal/qf:adopt — Interactive, no arguments required
Derive the feature slug from the project directory name (convert to kebab-case).
my-project)"./plans/{feature-slug}/FEATURE_SLUG for all subsequent steps.Ask all 5 questions as a single batch. Use AskUserQuestion with structured options where applicable.
Present as: "Before I scan your project, I need a few quick answers to guide the analysis."
Q1 — Primary Language (free text): "What is the primary programming language of this project?"
Q2 — Project Structure (choice): "What is the project structure type?"
monolith, monorepo, microservicesQ3 — Test Suite (choice): "Does this project have a test suite?"
yes, no, partialQ4 — Documentation (choice): "Does this project have existing documentation?"
yes, no, partialQ5 — Adoption Goal (choice): "What is your primary goal after adoption?"
new feature, maintenance, bothCollect answers into a PreScanAnswers object:
primary_language: "" # from Q1
project_type_hint: "" # "monolith" | "monorepo" | "microservices"
has_tests: "" # "yes" | "no" | "partial"
has_docs: "" # "yes" | "no" | "partial"
adoption_goal: "" # "new_feature" | "maintenance" | "both"
Scanner MUST complete before Phase 2 agents are spawned. Do NOT run scanner in parallel with other agents.
READ agents/adopt-scanner.md (if it exists) before spawning.
Spawn via Task(subagent_type: "planner", name: "adopt-scanner") with this prompt:
You are adopt-scanner. Scan the project at {CWD}.
## PreScanAnswers
{PreScanAnswers YAML block}
## Instructions
Read agents/adopt-scanner.md for your full scanning protocol.
Your output MUST be a ScannerPhaseResult YAML block containing both ScannerFindings and FileMap,
as defined in agents/adopt-scanner.md → Output section.
CK Context:
- Work dir: {CWD}
- Plans: plans/
- Branch: {current git branch}
- Active plan: plans/{feature-slug}/
- Commits: conventional (feat:, fix:, docs:, refactor:, test:, chore:)
- Doc lookup: {doc_lookup}
- Code graph: {code_graph}
Wait for adopt-scanner to complete. Capture the ScannerPhaseResult:
scanner_findings: {} # ScannerFindings (M1 Contract 1)
file_map: {} # FileMap (M2 Contract 8)
If adopt-scanner errors or times out:
scannerFailed: truescanner_findings to empty ScannerFindings with error.occurred: truefile_map to empty FileMapAfter scanner completes (or fails), spawn both Phase 2 agents simultaneously. Both receive the same ScannerFindings, FileMap, and PreScanAnswers.
READ agents/adopt-feature-extractor.md (if it exists) before spawning.
Spawn via Task(subagent_type: "planner", name: "adopt-feature-extractor") with this prompt:
You are adopt-feature-extractor. Analyze the project's features and modules.
## ScannerFindings
{ScannerFindings YAML block}
## FileMap
{FileMap YAML block}
## PreScanAnswers
{PreScanAnswers YAML block}
## Instructions
Read agents/adopt-feature-extractor.md for your full protocol.
Your output MUST be a FeatureUnits YAML block as defined in agents/adopt-feature-extractor.md → Output section.
CK Context:
- Work dir: {CWD}
- Plans: plans/
- Branch: {current git branch}
- Active plan: plans/{feature-slug}/
- Doc lookup: {doc_lookup}
- Code graph: {code_graph}
READ agents/adopt-doc-generator.md (if it exists) before spawning.
Spawn via Task(subagent_type: "planner", name: "adopt-doc-generator") with this prompt:
You are adopt-doc-generator. Generate architecture documentation for the project.
## ScannerFindings
{ScannerFindings YAML block}
## FileMap
{FileMap YAML block}
## PreScanAnswers
{PreScanAnswers YAML block}
## Instructions
Read agents/adopt-doc-generator.md for your full protocol.
Your output MUST be a DocArtifacts YAML block as defined in agents/adopt-doc-generator.md → Output section.
CK Context:
- Work dir: {CWD}
- Plans: plans/
- Branch: {current git branch}
- Active plan: plans/{feature-slug}/
- Doc lookup: {doc_lookup}
- Code graph: {code_graph}
| Agent fails | Behavior |
|---|---|
| adopt-feature-extractor fails | Non-blocking — set featureExtractorFailed: true, features: [], skip .memory/ |
| adopt-doc-generator fails | Non-blocking — set docGeneratorFailed: true, skip diagrams |
| Both Phase 2 agents fail | Scaffolder falls back to M1 behavior (no .memory/, no diagrams) |
Once both Phase 2 agents complete (or fail), run inline synthesis. This is NOT a separate agent — the orchestrator performs reconciliation using the rules below.
Collect inputs:
FeatureUnits — from feature extractor (or empty if failed)DocArtifacts — from doc generator (or null if failed)ScannerFindings.project_structure.key_directories — from scannerInitialize:
unified_model:
scanner_findings: {} # original ScannerFindings (unchanged)
file_map: {} # original FileMap (unchanged)
features: [] # will be populated after reconciliation
doc_artifacts: {} # DocArtifacts (unchanged, or null)
conflicts: [] # unresolved conflicts to surface at review gate
synthesis_notes: [] # log of every reconciliation action taken
Rule 1 — Module Count Check:
Condition: abs(features.length - key_dirs.length) > max(features.length, key_dirs.length) / 2
Where features.length is the count from FeatureUnits and key_dirs.length is the count of
entries in ScannerFindings.project_structure.key_directories.
Action: Do NOT auto-reconcile. Add to synthesis_notes:
"Module count mismatch: feature extractor found {N} features, scanner found {M} key directories.
Difference exceeds 50% threshold — flagged for user review."
Rule 2 — Naming Normalization:
Condition: A feature from FeatureUnits and a module from doc_artifacts.module_map appear to
refer to the same entity but use different names (case-insensitive comparison, ignoring hyphens/underscores).
Action:
doc_artifacts.module_map[].name to match- type: "naming"
subject: "{the module in question}"
views:
extractor: "{feature extractor name}"
doc_generator: "{doc generator name}"
resolution: "normalized_to_extractor"
synthesis_notes: "Naming normalized: '{doc_gen_name}' → '{extractor_name}'"Rule 3 — Dependency Merge:
Condition: ScannerFindings.tech_stack contains technology-level dependencies AND
FeatureUnits.features[].dependencies contains feature-level dependencies.
Action: Merge both into unified_model.features[].dependencies. Tech-stack entries are prefixed
with tech: (e.g., tech:postgresql) to distinguish from feature-level entries.
Add to synthesis_notes: "Dependencies merged: tech-stack + feature-level deps unified."
Rule 4 — Conflict Resolution:
Condition: Any 2-way disagreement not covered by Rules 1–3 (e.g., feature existence dispute: extractor claims a feature exists, doc generator's module_map does not list it, or vice versa).
Action:
confidence: low- type: "feature_existence" # or "dependency" as appropriate
subject: "{subject of disagreement}"
views:
extractor: "{extractor's view}"
doc_generator: "{doc generator's view}"
resolution: "user_review_required"
synthesis_notes: "Conflict flagged: {subject} — user review required."Rule 5 — Synthesis Notes:
Every reconciliation action from Rules 1–4 MUST be recorded in synthesis_notes[].
Empty synthesis_notes means no reconciliation was necessary.
After reconciliation, copy the (now-reconciled) features from FeatureUnits into
unified_model.features. Each feature retains its confidence from the feature extractor,
degraded by one level (high→medium, medium→low) if it was involved in a conflict.
⚠️ ASSUMPTION: Synthesis runs without spawning an agent. All reconciliation is inline prose logic executed by the orchestrator. If synthesis complexity grows in future milestones, consider extracting to a dedicated adopt-synthesizer agent.
Pass the UnifiedProjectModel to the scaffolder. Do NOT pass raw ScannerFindings directly.
READ agents/adopt-scaffolder.md (if it exists) before spawning.
Spawn via Task(subagent_type: "fullstack-developer", name: "adopt-scaffolder") with this prompt:
You are adopt-scaffolder. Scaffold the QuangFlow directory structure for the adopted project.
## UnifiedProjectModel
{UnifiedProjectModel YAML block}
## PreScanAnswers
{PreScanAnswers YAML block}
## Instructions
Read agents/adopt-scaffolder.md for your full scaffolding protocol.
Use the UnifiedProjectModel (not raw ScannerFindings) as your primary input.
Your output MUST be a DraftArtifacts YAML block as defined in agents/adopt-scaffolder.md → Output section.
CK Context:
- Work dir: {CWD}
- Feature slug: {feature-slug}
- Plans: plans/
- Branch: {current git branch}
- Active plan: plans/{feature-slug}/
- Commits: conventional (feat:, fix:, docs:, refactor:, test:, chore:)
- Doc lookup: {doc_lookup}
- Code graph: {code_graph}
Wait for adopt-scaffolder to complete. Capture DraftArtifacts.
State: AWAITING_REVIEW
Present to the user in this order:
## Adoption Draft — Review Required
### High Confidence
{List all findings derived from clear signals (manifests, config files, dedicated directories).
Format: "- {finding}" for each item.
If none: "No high-confidence findings."}
### Medium Confidence
{List all findings derived from pattern-based inference (import clusters, naming heuristics).
Format: "- {finding} ⚠️ inferred"
If none: "No medium-confidence findings."}
### Low Confidence
{List all findings derived from heuristic guesses or answers-only mode.
Format: "- {finding} ⚠️ LOW — review carefully"
If none: "No low-confidence findings."}
### Feature Memory Units
{For each feature in UnifiedProjectModel.features:
- .memory/{feature.name}/ [confidence: {feature.confidence}]
If features is empty (extractor failed): "⚠️ Feature memory skipped — feature extractor failed."}
### Architecture Diagrams
{If doc_artifacts is not null:
Render component_diagram inline (Mermaid fenced block)
Render dependency_graph inline (Mermaid fenced block)
If doc_artifacts is null (doc generator failed):
"⚠️ Architecture diagrams skipped — doc generator failed."}
### Synthesis Conflicts
{If UnifiedProjectModel.conflicts is non-empty:
For each conflict:
⚠️ [{conflict.type}] {conflict.subject}
Extractor: {conflict.views.extractor}
Doc generator: {conflict.views.doc_generator}
Resolution: {conflict.resolution}
If empty: "No synthesis conflicts."}
### Gap Findings
{Format ScannerFindings.gaps as a numbered list:
1. [{type}] {detail}
...or "No gaps detected." if empty}
### Partial Adoption Report (if partial_adoption: true)
Merged: {DraftArtifacts.partial_adoption_details.merged}
Preserved: {DraftArtifacts.partial_adoption_details.preserved}
Updated: {DraftArtifacts.partial_adoption_details.updated}
### Scanner Warning (if scanner_failed: true)
⚠️ Scanner failed: {error message}
CONTEXT.md was generated from your answers only.
Fields marked ⚠️ ASSUMPTION need manual review before proceeding.
---
Type APPROVE to finalize, or describe what to change.
Transition to APPROVED → proceed to Step 8.
Transition to REJECTED_WITH_FEEDBACK.
Determine which agent(s) to re-run based on feedback content using the extended routing table:
| Feedback about... | Re-run target | Cascade |
|---|---|---|
| Tech stack, structure, scanning depth | adopt-scanner | → then re-run BOTH Phase 2 agents → synthesis → scaffolder |
| Feature detection, memory units, feature names | adopt-feature-extractor only | → re-synthesis → scaffolder |
| Diagrams, module map, README sections | adopt-doc-generator only | → re-synthesis → scaffolder |
| CONTEXT.md formatting or structure | adopt-scaffolder only | — |
| Everything / major rethink | all agents | Full re-run (scanner → Phase 2 → synthesis → scaffolder) |
⚠️ ASSUMPTION: Targeted re-runs preserve the previous agent output from un-targeted agents. Example: re-running adopt-doc-generator reuses the existing FeatureUnits from the prior feature extractor run — it does NOT re-run the feature extractor.
Re-spawn the relevant agent(s) with original inputs + feedback appended:
## User Feedback on Previous Draft
{feedback text}
Please incorporate this feedback and produce an updated output.
After re-run completes, re-run synthesis with the updated outputs, then re-run scaffolder if
synthesis produced a changed UnifiedProjectModel. Return to AWAITING_REVIEW (re-present the draft).
No retry limit.
On APPROVED:
Remove the DRAFT marker from CONTEXT.md:
Remove: > **STATUS: DRAFT** — Awaiting user approval via /qf:adopt review gate.
Remove DRAFT markers from all .memory/ files written during scaffolding:
In each .memory/ file, remove the line: <!-- Generated by /qf:adopt — STATUS: DRAFT -->
Replace it with: <!-- Generated by /qf:adopt — approved {ISO-8601 date} -->
Write adoption metadata to ## Locked Decisions in CONTEXT.md:
## Locked Decisions
- Adopted on {ISO-8601 date} via /qf:adopt
- Tech stack detected: {comma-separated summary: languages + frameworks + databases}
- Project structure: {ScannerFindings.project_structure.pattern, or "not determined"}
- Scan found {N} gap(s): {comma-separated gap types, or "none"}
- Scanner failed: {yes/no}{if yes: " — fields marked ⚠️ ASSUMPTION need manual review"}
- Feature extractor: {ok / failed — .memory/ skipped}
- Doc generator: {ok / failed — diagrams skipped}
- Overall confidence: {DraftArtifacts.overall_confidence}
- Synthesis conflicts: {count, or "none"}
./plans/{feature-slug}/OPEN_QUESTIONS.md if it does not exist:# Open Questions — {feature-slug}
(populated during brainstorm and later phases)
plans/{feature-slug}/CONTEXT.md."
If features were written: "Feature memory units saved to .memory/."Present the next-command choice based on adoption_goal from PreScanAnswers:
## What's next?
{if adoption_goal == "new_feature" or "both"}
Recommended for your goal:
1. /qf:1-brainstorm — Discover requirements, edge cases, milestones, and team composition
↳ Best if you have a new feature or enhancement to build on this project
2. /qf:5-maintain — Post-ship systematic debugging, structured log scan, hotfix
↳ Best if you want to fix bugs or maintain existing functionality
{if adoption_goal == "maintenance"}
Recommended for your goal:
1. /qf:5-maintain — Post-ship systematic debugging, structured log scan, hotfix
↳ Recommended based on your maintenance goal
2. /qf:1-brainstorm — Discover requirements, edge cases, milestones, and team composition
↳ If you decide to add new features later
Type 1 or 2 to continue, or type the command directly.
Pre-select suggestion based on adoption_goal:
new_feature → suggest /qf:1-brainstorm (option 1)maintenance → suggest /qf:5-maintain (option 1)both → suggest /qf:1-brainstorm (option 1, note both are equally valid)| Error | Behavior |
|---|---|
| Scanner agent fails / times out | Set scannerFailed: true, continue with PreScanAnswers-only context; all Phase 2 agents receive empty findings (low confidence) |
| Feature extractor fails | Non-blocking — set featureExtractorFailed: true, features: [], skip .memory/ |
| Doc generator fails | Non-blocking — set docGeneratorFailed: true, skip diagrams |
| Both Phase 2 agents fail | Scaffolder falls back to M1 behavior (no .memory/, no diagrams) |
| Scaffolder agent fails | Report error, abort — scaffolder is blocking (cannot finalize without CONTEXT.md) |
| Partial adoption conflict | Scaffolder presents merge/skip choices to user before proceeding |
| User loops on review gate | Accept indefinitely — no retry limit |
| plans/{slug}/ already exists | Treat as partial adoption — scaffolder handles merge/skip |
See _protocols/_shared.md → Output Rule. Save files silently — do NOT print file contents.
Mention file paths only.
Append an adoption row to plans/{feature-slug}/PROGRESS.md:
| adopt | {ISO date} | scanner_failed={yes/no}, partial={yes/no}, gaps={N}, goal={adoption_goal}, extractor_failed={yes/no}, doc_gen_failed={yes/no}, conflicts={N}, confidence={overall_confidence} |
After router choice, tell user:
Project adopted. Context at `plans/{feature-slug}/CONTEXT.md`.
Also available: `/qf:status` (check status)