pplx-sdk Development Meta-Skill

When to use

Subagent Architecture

context: fork

┌───────────────────────────────────────────────────────┐
│                  orchestrator                         │
│  (meta-orchestrator, delegates subtasks)              │
├───────────────────────────────────────────────────────┤
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ code-reviewer │  │ test-runner   │                  │
│  │ (read-only)   │  │ (run & fix)   │                  │
│  │ view,grep,    │  │ bash,view,    │                  │
│  │ glob,bash     │  │ edit,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ scaffolder    │  │ sse-expert    │                  │
│  │ (create new)  │  │ (streaming)   │                  │
│  │ view,edit,    │  │ view,edit,    │                  │
│  │ bash,grep     │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ reverse-     │  │ architect     │                  │
│  │  engineer    │  │ (diagrams &   │                  │
│  │ (API disc.)  │  │  design)      │                  │
│  │ view,edit,   │  │ view,edit,    │                  │
│  │ bash,grep    │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ spa-expert   │  │ codegraph     │                  │
│  │ (SPA RE,     │  │ (AST, deps,   │                  │
│  │  CDP, ext.)  │  │  knowledge)   │                  │
│  │ view,edit,   │  │ view,edit,    │                  │
│  │ bash,grep    │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
└───────────────────────────────────────────────────────┘

Subagent Definitions (

.claude/agents/

)

orchestrator

code-reviewer

test-runner

scaffolder

sse-expert

reverse-engineer

architect

spa-expert

codegraph

Skill Dependencies

Project-Specific Skills (repo root)

code-review

code-review/SKILL.md

code-reviewer

test-fix

test-fix/SKILL.md

test-runner

scaffold-module

scaffold-module/SKILL.md

scaffolder

sse-streaming

sse-streaming/SKILL.md

sse-expert

reverse-engineer

reverse-engineer/SKILL.md

reverse-engineer

architecture

architecture/SKILL.md

architect

spa-reverse-engineer

spa-reverse-engineer/SKILL.md

spa-expert

code-analysis

code-analysis/SKILL.md

codegraph

Community Skills (installed via

npx skills

)

python-testing-patterns

wshobson/agents

python-type-safety

wshobson/agents

python-error-handling

wshobson/agents

python-design-patterns

wshobson/agents

api-design-principles

wshobson/agents

async-python-patterns

wshobson/agents

skill-creator

anthropics/skills

mcp-builder

anthropics/skills

webapp-testing

anthropics/skills

ast-grep

ast-grep/agent-skill

knowledge-graph-builder

daffy0208/ai-dev-standards

steering

nahisaho/codegraphmcpserver

Workflow: New Feature

[plan] → [explore] → [research] → [implement] → [test] → [review] → [done]

1. Plan —

   orchestrator

   decomposes the task, identifies target layer
2. Explore —

   code-reviewer

   (read-only fork) analyzes existing code and dependencies
3. Research —

   reverse-engineer

   or

   sse-expert

   (fork) studies API behavior, reads docs, gathers context needed before implementation
4. Scaffold —

   scaffolder

   (fork) creates files from templates
5. Implement —

   sse-expert

   or

   scaffolder

   (fork) writes the code
6. Test —

   test-runner

   (fork) runs pytest, fixes failures
7. Review —

   code-reviewer

   (fork) validates architecture compliance
8. Verify —

   ruff check --fix . && ruff format . && mypy pplx_sdk/ && pytest -v

Workflow: Bug Fix

1. Reproduce —

   test-runner

   (fork) runs failing test with

   -v

2. Research —

   code-reviewer

   (fork) traces the code path, reads related modules and tests
3. Diagnose —

   test-runner

   reads traceback, identifies root cause
4. Fix —

   test-runner

   edits source/test, applies

   python-error-handling

   patterns
5. Verify —

   test-runner

   runs full suite

Workflow: SSE/Streaming Work

1. Research —

   sse-expert

   (fork) reviews SSE protocol spec, existing transport code, and API response patterns
2. Implement —

   sse-expert

   writes streaming code, applies

   async-python-patterns

3. Test —

   test-runner

   (fork) runs tests with mock SSE responses
4. Review —

   code-reviewer

   (fork) validates transport layer compliance

Workflow: API Discovery (Reverse Engineering)

[capture] → [research] → [document] → [scaffold] → [test] → [review]

1. Capture —

   reverse-engineer

   (fork) analyzes cURL/traffic from perplexity.ai DevTools
2. Research —

   reverse-engineer

   studies request/response patterns, tests variations, maps edge cases and auth flows
3. Document —

   reverse-engineer

   writes endpoint documentation with field types and examples
4. Scaffold —

   scaffolder

   (fork) creates Pydantic models and service methods from schema
5. Implement —

   sse-expert

   or

   scaffolder

   implements transport and domain code
6. Test —

   test-runner

   (fork) validates with mock responses matching discovered schemas
7. Review —

   code-reviewer

   (fork) ensures architecture compliance

Workflow: API Endpoint

1. Research —

   code-reviewer

   (fork) studies existing endpoints and

   api-design-principles

   patterns
2. Design —

   code-reviewer

   reviews proposed schema against REST conventions
3. Implement —

   scaffolder

   (fork) creates FastAPI endpoint
4. Test —

   test-runner

   (fork) validates with pytest-httpx mocks

Workflow: Architecture Design & Visualization

[analyze] → [research] → [diagram] → [validate] → [document]

1. Analyze —

   architect

   (fork) reads existing code, maps imports and layer dependencies
2. Research —

   architect

   studies the components involved and their relationships
3. Diagram —

   architect

   produces Mermaid diagrams (layer map, sequence, class hierarchy, state machine)
4. Validate —

   architect

   checks for circular deps, upward imports, protocol conformance
5. Document —

   architect

   embeds diagrams in README, docs, or PR descriptions

Workflow: SPA Reverse Engineering

[detect] → [research] → [intercept] → [extract] → [code-graph] → [document] → [implement]

1. Detect —

   spa-expert

   (fork) identifies the SPA stack (React version, bundler, state management, service workers)
2. Research —

   spa-expert

   studies the SPA internals, React component tree, and network patterns
3. Intercept —

   spa-expert

   captures network traffic via CDP, Chrome extension, or DevTools
4. Extract —

   spa-expert

   extracts React state shapes, API schemas, and Workbox cache strategies
5. Code Graph —

   codegraph

   (fork) analyzes SPA source code: component tree, import graph, hook chains, TypeScript types; cross-references with

   spa-expert

   runtime findings
6. Document —

   reverse-engineer

   +

   spa-expert

   map runtime + static discoveries to SDK architecture
7. Implement —

   scaffolder

   creates models and services;

   spa-expert

   builds tools/extensions

Workflow: Code Analysis & Knowledge Graph

[parse] → [graph] → [analyze] → [report] → [act]

1. Parse —

   codegraph

   (fork) parses source AST: Python via

   ast

   module, JavaScript/TypeScript via grep-based import parsing
2. Graph —

   codegraph

   builds dependency graph (module-to-module imports) and knowledge graph (Python: IMPORTS, INHERITS, IMPLEMENTS, CALLS, RAISES; SPA: RENDERS, USES_HOOK, CALLS_API, PROVIDES, CONSUMES)
3. Analyze —

   codegraph

   detects patterns: circular deps, layer violations, dead code, complexity hotspots (Python); barrel file cycles, prop drilling, orphan routes (SPA)
4. Report —

   codegraph

   produces structured insights report with Mermaid diagrams and actionable findings
5. Act — Delegate findings:

   architect

   updates diagrams,

   code-reviewer

   reviews violations,

   scaffolder

   fixes gaps,

   spa-expert

   cross-references runtime analysis

Project Quick Reference

# Install dependencies
pip install -e ".[dev]"

# Install/update community skills
npx skills add wshobson/agents --skill python-testing-patterns --skill python-type-safety --skill python-error-handling --skill python-design-patterns --skill api-design-principles --skill async-python-patterns --agent github-copilot -y
npx skills add anthropics/skills --skill skill-creator --skill mcp-builder --skill webapp-testing --agent github-copilot -y
npx skills add ast-grep/agent-skill --skill ast-grep --agent github-copilot -y
npx skills add "daffy0208/ai-dev-standards@knowledge-graph-builder" --agent github-copilot -y
npx skills add nahisaho/codegraphmcpserver --skill steering --agent github-copilot -y

# Lint, format, type-check, test
ruff check --fix . && ruff format .
mypy pplx_sdk/ --ignore-missing-imports
pytest tests/ -v --cov=pplx_sdk

# Manage skills
npx skills list          # Show installed skills
npx skills check         # Check for updates
npx skills update        # Update all skills

Architecture Invariants

1. Layer dependencies:

   core/ → shared/ → transport/ → domain/ → client.py

   (never reverse)
2. Exception hierarchy: All errors extend

   PerplexitySDKError

3. Type annotations: 100% coverage,

   from __future__ import annotations

4. Google docstrings: On all public APIs
5. Protocol pattern: Use

   typing.Protocol

   , never ABC