Codebase Architect

Codebase Architect

Generate exhaustive architecture documentation for any WordPress plugin/theme with built-in self-checking, progress tracking, and verification loops.

When to use

Use this skill when:

• Creating comprehensive architecture documentation for a plugin/theme
• Auditing what exists in a codebase (classes, functions, hooks, APIs)
• Verifying existing documentation completeness
• Onboarding to a new codebase and need a reference guide

Inputs required

• Path to the plugin or theme directory.
• Scope level: architectural, hybrid, reference, or verify.
• Output directory for documentation files.

Scope Parameter

Procedure

0) Initialize manifest

Create manifest directory and tracking files:

mkdir -p <output-dir>/manifest

Create manifest files for each category:

• classes.txt, functions.txt, hooks.txt
• rest-endpoints.txt, ajax-handlers.txt
• js-files.txt, db-tables.txt, templates.txt
• blocks.txt, shortcodes.txt, widgets.txt
• cpt-taxonomies.txt, admin-pages.txt
• cron-jobs.txt, cli-commands.txt
• PROGRESS.md (master tracker)

Read:

• references/manifest-format.md

1) Run enumeration (parallel agents)

Launch 16 enumeration agents in parallel to populate manifests:

1. Classes: grep -rn "^class \|^abstract class \|^trait \|^interface "
2. Functions: grep -rn "^function [a-z_]"
3. Action hooks: grep -rohn "do_action\s*(\s*['\"][^'\"]*['\"]"
4. Filter hooks: grep -rohn "apply_filters\s*(\s*['\"][^'\"]*['\"]"
5. REST endpoints: grep -rn "register_rest_route"
6. AJAX handlers: grep -rn "wp_ajax_"
7. JavaScript files: find -name "*.js"
8. DB tables: grep -rn "CREATE TABLE"
9. Templates: find -name "*.php" -path "*/templates/*"
10. Blocks: find -name "block.json"
11. Shortcodes: grep -rn "add_shortcode"
12. Widgets: grep -rn "extends WP_Widget"
13. CPT/Taxonomies: grep -rn "register_post_type\|register_taxonomy"
14. Admin pages: grep -rn "add_menu_page\|add_submenu_page"
15. Cron jobs: grep -rn "wp_schedule_event"
16. CLI commands: grep -rn "WP_CLI::add_command"

Read:

• references/enumeration-commands.md

2) Document (with progress updates)

For each category, launch documentation agents that:

1. Read from manifest
2. Document each item
3. Update manifest status: pending → documented
4. Update PROGRESS.md

Read:

• references/documentation-agents.md

3) Self-verification loop

After documentation completes:

1. Count items with status:pending (gaps)
2. Count items with status:documented (done)
3. If coverage < 100%, trigger gap filling
4. Run cross-reference check

Read:

• references/verification-loop.md

4) Gap filling (automatic)

For any gaps found:

1. Read source code for item
2. Generate documentation
3. Update manifest
4. Trigger verification again

5) Final validation

When verification passes:

• Structure check (TOC, links, code examples)
• Completeness check (all categories at 100%)
• Quality check (each item has required fields)
• Generate FINAL_REPORT.md

Verification

Documentation is COMPLETE when:

• All 15 manifest categories at 100% coverage
• Verification loop passes without finding new gaps
• Cross-reference check passes
• Final validation checklist complete
• FINAL_REPORT.md generated

Failure modes / debugging

• Enumeration returns 0 items:
  • Path doesn't exist, wrong grep pattern, vendor folder included
• Documentation incomplete after multiple passes:
  • Check for status:error items in manifests
  • Review Gap Log in PROGRESS.md
• Cross-reference failures:
  • Stale references from renamed/moved files

Read:

• references/debugging.md

Escalation

• For very large codebases (1000+ files), use architectural scope
• If enumeration takes too long, exclude vendor/node_modules
• For manual review items, document what's known and mark as partial

Output Files

<output-dir>/
├── PLUGIN_ARCHITECTURE.md  # Final documentation
├── manifest/
│   ├── PROGRESS.md         # Progress tracker
│   ├── classes.txt
│   ├── functions.txt
│   └── ... (other manifests)
└── FINAL_REPORT.md         # Validation report