skills.rest
AZidan
AZidanCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

archflow-doctor

Diagnoses Archflow environment tooling and project state, reporting PASS, WARN, or FAIL with fixes.

28|4|Updated Mar 12, 2026
Search Tags:#troubleshooting#drift detection#health check#diagnostics#schema validation#environment validation#archflow
One-click install
npx skills add https://github.com/AZidan/archflow --skill archflow-doctor-azidan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: archflow-doctor
Source: https://github.com/AZidan/archflow/tree/main/adapters/copilot/.github/skills/archflow-doctor
Command: npx skills add https://github.com/AZidan/archflow --skill archflow-doctor-azidan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Archflow projects depend on external tooling (git, node, codemap) and a consistent .archflow/ state directory, and silent drift between a project and the installed plugin causes confusing failures. This Skill runs a structured health check that identifies what is missing, what is degraded, and exactly how to fix it. ## Core Features & Use Cases - Environment and tooling checks: Verifies git, node, python3/PyYAML, codemap, and end-to-end test tooling, classifying each as PASS, WARN, or FAIL with the concrete cost of leaving it unfixed. - Project state validation: Inspects .archflow/ files such as current-phase.yaml, project-settings.yaml, and roadmap.yaml, with optional --validate schema validation and --fix repairs for upgrade drift, settings splits, and stack detection. - Use Case: A user reports that agents stopped working after a plugin update. Run the doctor to discover the project's framework files are behind the installed plugin, then apply --fix to refresh them with backups. ## Quick Start Ask the agent to run /archflow-doctor to check the environment and project state, optionally adding --validate or --fix.

Frequently Asked Questions about archflow-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if my Archflow project is set up correctly?▼

Run /archflow-doctor with no arguments. It checks tooling (git, node, python3, codemap), end-to-end test tooling, and every .archflow/ state file, then reports PASS, WARN, or FAIL with the exact commands to fix each issue.

How do I fix drift between my Archflow project and the installed plugin?▼

Run /archflow-doctor --fix. It shows a dry-run plan first, backs up originals to .archflow/backup-upgrade-{timestamp}/, then refreshes stale framework files, converts tech_stack to stack, and detects missing stack fields from repo manifests.

Does archflow-doctor install missing tools automatically?▼

No. Without --fix it never installs anything, never edits state, and never changes a phase. Even with --fix it only repairs project files after approval; tool installs like codemap are always offered as commands for the user to run.

What does the --validate flag do in archflow-doctor?▼

The --validate flag runs the plugin's validate_archflow.py script against every .archflow/ state file, checking them against their schemas. A schema violation is reported as a FAIL since state files are the contract every agent reads.

Why does archflow-doctor report codemap as missing?▼

codemap is an optional token-optimization tool that lets agents navigate by structural index instead of reading whole files, cutting navigation tokens by roughly 60-80%. Its absence is a WARN, not a FAIL, because agents fall back to Glob/Grep.

When should I run archflow-doctor versus archflow-onboard?▼

Run archflow-doctor when something is not working or to audit an existing project's health; it is the recommended first step for any 'isn't working' report. Use /archflow-onboard to set up a project that has no .archflow/ directory at all.

Related Skills

Explore More Software Engineering Skills→
msaid1976msaid1976

speckit-git-initialize

Initialize a Git repository with an initial commit in spec-kit projects.

Community
Basic
edercnjedercnj

x-implement-story

Orchestrate story execution by delegating phases to specialized sub-skills.

Community
Advanced
yakeworldyakeworld
6

privacy-scan

Scans Git pushes for API keys, tokens, passwords, and phone numbers before publishing.

Community
Intermediate
agentic-inagentic-in
577

mcporter

Discover, inspect, and call MCP servers from the terminal.

Official
Intermediate