Analyze tech stack, run dev tooling, and remediate code quality issues
Analyzes tech stack, runs dev tooling, and remediates code quality issues
/plugin marketplace add moshehbenavraham/apex-spec-system/plugin install apex-spec@apex-spec-marketplaceAdd and validate local dev tooling one bundle at a time. Follows the universal 9-step flow shared with /pipeline and /infra.
Industry standard order (fast to slow, format before validate):
| Priority | Bundle | Contents |
|---|---|---|
| 1 | Formatting | Formatter (Prettier, Biome, Black, Ruff format) |
| 2 | Linting | Linter (ESLint, Biome, Ruff, Clippy) |
| 3 | Type Safety | Type checker (TypeScript, mypy, Pyright) |
| 4 | Testing | Test runner + coverage (Jest, Vitest, pytest, pytest-cov) |
| 5 | Observability | Structured logger + error capture (structlog, pino, tracing, slog) |
| 6 | Git Hooks | Pre-commit hooks (husky, pre-commit, lefthook) |
| Flag | Default | Description |
|---|---|---|
--dry-run | false | Preview what would happen without changes |
--skip-install | false | Don't install missing tools |
--verbose | false | Show full tool output |
Check for .spec_system/CONVENTIONS.md
Check for .spec_system/audit/known-issues.md
Check git status
If --dry-run: Skip to Dry Run Output
Compare Local Dev Tools table against 6-bundle master list:
If all bundles configured: "All recommended local dev tools configured. Jumping to Step 5."
Pick the highest-priority missing bundle from Step 2.
Output: "Selected: [Bundle Name] - not yet configured"
Install and configure the single selected bundle missing.
Detection by language (from CONVENTIONS.md Stack section):
| Language | Formatter | Linter | Type Checker | Test Framework | Logger | Git Hooks |
|---|---|---|---|---|---|---|
| Python | Ruff | Ruff | mypy | pytest + pytest-cov | structlog | pre-commit |
| TypeScript | Biome | Biome | tsc (strict) | Vitest | pino | husky + lint-staged |
| JavaScript | Biome | Biome | - | Vitest | pino | husky + lint-staged |
| Rust | rustfmt | Clippy | (built-in) | cargo test | tracing | pre-commit |
| Go | gofmt | golangci-lint | (built-in) | go test | log/slog | pre-commit |
For monorepos: Install at root if shared, or per-package if stack differs.
--skip-install: Provide manual instructions, continuePurpose: Set up structured logging with AI-friendly error capture.
For all languages, create:
logs/ directory in project rootlogs/.gitignore with contentlogs/last_error_<timestamp>.json, ex: logs/last_error_2025-01-01T12:00:00.000Z.jsonlast_error.json schema (AI-friendly structured error context):
{
"timestamp": "2025-01-01T12:00:00.000Z",
"level": "error",
"msg": "Error description",
"error": {
"type": "ErrorClassName",
"message": "Detailed error message",
"stack": "Stack trace..."
},
"context": {}
}
Language-specific setup examples:
| Language | Install | Config File | Error Handler |
|---|---|---|---|
| Python | pip install structlog | src/logging_config.py | write_last_error() processor |
| TypeScript | npm install pino | src/logger.ts | logMethod hook |
| JavaScript | npm install pino | src/logger.js | logMethod hook |
| Rust | Add tracing, tracing-subscriber to Cargo.toml | src/logging.rs | capture_error() function |
| Go | (stdlib) | internal/logging/logging.go | CaptureError() function |
Run ALL configured tools (not just the new one):
Observability validation:
logs/ directory existslogs/.gitignore has correct patternslogs/last_error_<timestamp>.json is created with valid JSONFor monorepos: Run per package, collect results.
Capture all output. Parse for errors, warnings, fixes applied.
For each issue found in Step 5:
Guardrail: After any fix, verify syntax/compilation. If broken after 2 retries, revert.
Filter out issues matching known-issues.md patterns - report separately as "Known".
If a new bundle was added, update .spec_system/CONVENTIONS.md:
Update the Local Dev Tools table:
| Category | Tool | Config |
|----------|------|--------|
| Formatter | Ruff | ruff.toml | <-- was "not configured"
For monorepos, show per-package:
[apps/web] Formatter: 12 fixed | Linter: 3 remain
[apps/api] Formatter: 8 fixed | Types: 2 errors
For single repos:
REPORT
- Added: Formatting (Ruff)
- Config: ruff.toml created
- Fixed: 47 format issues, 12 lint errors
- Remaining: 3 type errors in src/api/handlers.ts:45, :67, :89
- Known: 5 issues in src/legacy/** (ignored per known-issues.md)
If issues remain:
ACTION REQUIRED:
1. Fix type errors in src/api/handlers.ts
Rerun /audit after addressing these issues.
If new bundle added configured and passing:
New dev tool bundle configured and all tools passing.
Recommendation: Run /pipeline
If all 6 bundles configured and passing:
All local dev tools configured and all tools passing.
Recommendation: Run /pipeline
AUDIT PREVIEW (DRY RUN)
Repository: monorepo (Turborepo)
Packages: apps/web, apps/api, packages/shared
Stack: Python 3.12, Node 20
Package managers: uv, pnpm
Configured: Formatting, Linting, Type Safety, Testing
Missing: Observability, Git Hooks
Would add: Observability
Would install: structlog (apps/api), pino (apps/web, packages/shared)
Would create: logs/ directory with .gitignore
Would create: src/logging_config.py (apps/api), src/logger.ts (apps/web)
Would run: ruff format, ruff check, biome format, biome lint, mypy, tsc, pytest, vitest
Run without --dry-run to apply.