1  ---
  2  title: 'Reusable Scaffolding'
  3  category: 'archive'
  4  last_verified: '2026-02-15'
  5  related_files:
  6    - 'src/utils/logger.js'
  7    - 'src/utils/error-handler.js'
  8    - 'src/utils/config.js'
  9    - 'scripts/generate-report.js'
 10  tags: ['reusable', 'scaffolding', 'testing', 'security', 'database', 'api', 'ai', 'llm']
 11  status: 'archived'
 12  ---
 13  
 14  # Reusable Project Scaffolding
 15  
 16  This document tracks components designed for reuse across future projects.
 17  
 18  ## Purpose
 19  
 20  The 333Method agent system, testing infrastructure, and development workflows are designed to be cloned to new software projects. This document maintains a checklist of reusable components and setup instructions.
 21  
 22  ## Core Components
 23  
 24  ### 1. Multi-Agent System
 25  
 26  **Location:** `src/agents/`
 27  
 28  **Reusable:**
 29  
 30  - Agent architecture (Monitor, Triage, Developer, QA, Security, Architect)
 31  - Database schema (`db/schema-agents.sql` or equivalent)
 32  - Task workflow with approval gates
 33  - CLI commands (`npm run agent:*`)
 34  
 35  **Project-Specific:**
 36  
 37  - Domain logic in agent task handlers
 38  - Project-specific prompts in `prompts/`
 39  
 40  **Setup Notes:**
 41  
 42  - `db/migrations/` folder structure
 43  - Agent configuration in `.env`
 44  - **CRITICAL BOOTSTRAP:** Monitor agent must be started with initial `scan_logs` task to begin self-scheduling recurring maintenance tasks
 45  
 46  ### 2. Testing Infrastructure
 47  
 48  **Location:** `tests/`, testing scripts in `package.json`
 49  
 50  **Reusable:**
 51  
 52  - Node.js native test runner configuration
 53  - c8 coverage tooling (target: 80%+)
 54  - Test file naming conventions (`*.test.js`, `*.integration.test.js`)
 55  - Mock patterns for external APIs
 56  - Coverage gates in CI
 57  
 58  **Project-Specific:**
 59  
 60  - Actual test cases
 61  - Domain-specific test utilities
 62  
 63  ### 3. Quality Automation
 64  
 65  **Location:** ESLint, Prettier, lint-staged configs
 66  
 67  **Reusable:**
 68  
 69  - `eslint.config.js` (flat config, max-lines, complexity limits)
 70  - `.prettierrc.json`
 71  - Git hooks via lint-staged (pre-commit)
 72  - `npm run quality-check` script
 73  - `npm run autofix` unified maintenance
 74  
 75  **Project-Specific:**
 76  
 77  - Project-specific ESLint rules
 78  - Code style preferences
 79  
 80  ### 4. Database Patterns
 81  
 82  **Location:** `db/`, migration scripts
 83  
 84  **Reusable:**
 85  
 86  - Migration system (`db/migrations/*.sql`)
 87  - Schema documentation approach
 88  - SQLite patterns (better-sqlite3)
 89  - Database backup scripts
 90  - Maintenance commands (VACUUM, ANALYZE, integrity_check)
 91  
 92  **Project-Specific:**
 93  
 94  - Domain tables
 95  - Business logic
 96  
 97  ### 5. Logging System
 98  
 99  **Location:** `src/utils/logger.js`, `logs/`
100  
101  **Reusable:**
102  
103  - Structured logging with daily rotation
104  - 7-day retention policy
105  - Domain-based log files (pipeline, outreach, etc.)
106  - Log level configuration (DEBUG, INFO, WARN, ERROR)
107  - `npm run logs:rotate` script
108  
109  **Project-Specific:**
110  
111  - Log categories/domains
112  - Alert thresholds
113  
114  ### 6. Error Handling
115  
116  **Location:** `src/utils/error-handler.js`
117  
118  **Reusable:**
119  
120  - `retryWithBackoff()` - exponential backoff with jitter
121  - `processBatch()` - concurrent batch processing
122  - Error classification system
123  - Graceful degradation patterns
124  
125  **Project-Specific:**
126  
127  - Domain-specific error types
128  - Retry strategies per API
129  
130  ### 7. CLI Architecture
131  
132  **Location:** `src/cli/`, npm scripts
133  
134  **Reusable:**
135  
136  - Command structure (stage commands, stats, admin)
137  - Help text patterns
138  - Progress indicators
139  - Color-coded output
140  
141  **Project-Specific:**
142  
143  - Domain commands
144  - CLI argument parsing for specific features
145  
146  ### 8. Documentation Standards
147  
148  **Location:** `docs/`, `CLAUDE.md`, `README.md`
149  
150  **Reusable:**
151  
152  - CLAUDE.md structure (autonomy preferences, tech stack, architecture)
153  - README.md sections (setup, commands, testing)
154  - TODO.md format (priorities, time estimates dual format)
155  - Changelog approach
156  - ADR (Architecture Decision Records) format
157  
158  **Project-Specific:**
159  
160  - Domain documentation
161  - Business logic explanations
162  
163  ### 9. Development Workflow
164  
165  **Location:** Git hooks, GitHub Actions (future)
166  
167  **Reusable:**
168  
169  - Branching strategy (feature/, fix/, refactor/, agent/)
170  - Commit message format (WHY not just WHAT)
171  - PR templates
172  - Code review checklist
173  - Architectural approval workflow
174  
175  **Project-Specific:**
176  
177  - Domain-specific review criteria
178  
179  ### 10. Dashboard & Reporting
180  
181  **Location:** `dashboard/`, `scripts/generate-report.js`
182  
183  **Reusable:**
184  
185  - Streamlit dashboard architecture
186  - Multi-page dashboard pattern
187  - Daily report generation (`npm run report:daily`)
188  - Report HTML templates
189  - Metrics tracking patterns
190  
191  **Project-Specific:**
192  
193  - Domain metrics
194  - Business KPIs
195  
196  ### 11. Security Practices
197  
198  **Location:** Security scripts, audit commands
199  
200  **Reusable:**
201  
202  - `npm run security` script (audit + snyk + semgrep)
203  - `.env.example` pattern (never commit secrets)
204  - Security agent role
205  - Dependency scanning automation
206  - OWASP best practices
207  
208  **Project-Specific:**
209  
210  - Domain-specific security concerns
211  - Compliance requirements
212  
213  ### 12. Configuration Management
214  
215  **Location:** `.env`, `src/utils/config.js` (if exists)
216  
217  **Reusable:**
218  
219  - Environment-based configuration
220  - `.env.example` documentation
221  - Configuration validation at startup
222  - Settings table for runtime config
223  
224  **Project-Specific:**
225  
226  - Domain configuration values
227  
228  ## Migration Checklist
229  
230  When cloning to a new project:
231  
232  1. **Copy Core Structure**
233     - [ ] `src/agents/` (all agents)
234     - [ ] `src/utils/logger.js`, `error-handler.js`
235     - [ ] `tests/` directory structure
236     - [ ] `docs/` directory structure
237     - [ ] `db/migrations/` structure
238  
239  2. **Copy Configuration Files**
240     - [ ] `eslint.config.js`
241     - [ ] `.prettierrc.json`
242     - [ ] `package.json` (testing, linting, git hooks sections)
243     - [ ] `.gitignore`
244     - [ ] `.env.example`
245  
246  3. **Copy Documentation Templates**
247     - [ ] `CLAUDE.md` (customize autonomy preferences)
248     - [ ] `README.md` (update project-specific sections)
249     - [ ] `docs/TODO.md` template
250  
251  4. **Set Up Database**
252     - [ ] Create agent-related tables (migrations)
253     - [ ] Initialize settings table
254     - [ ] Run integrity checks
255  
256  5. **Bootstrap Agent System**
257     - [ ] **CRITICAL:** Create initial Monitor agent `scan_logs` task
258     - [ ] Verify recurring tasks are scheduling correctly
259     - [ ] Set up agent task priorities with nice/ionice
260     - [ ] Configure maintenance tasks to use 1 core, lowest priority
261  
262  6. **Configure Quality Gates**
263     - [ ] Set coverage target (recommend 80%+)
264     - [ ] Configure ESLint rules (max-lines, complexity)
265     - [ ] Set up pre-commit hooks (lint-staged)
266     - [ ] Test `npm run quality-check`
267  
268  7. **Set Up Logging**
269     - [ ] Create `logs/` directory
270     - [ ] Configure log rotation (7-day default)
271     - [ ] Define domain-specific log files
272     - [ ] Test log output
273  
274  8. **Documentation**
275     - [ ] Update CLAUDE.md with project specifics
276     - [ ] Document new domains/patterns
277     - [ ] Create ADRs for architectural decisions
278  
279  9. **Testing Infrastructure**
280     - [ ] Run `npm test` to verify setup
281     - [ ] Check coverage reporting
282     - [ ] Set up integration test patterns
283  
284  10. **Agent Workflow**
285      - [ ] Configure approval workflow (Architect → PO → Developer → QA)
286      - [ ] Set up task priorities
287      - [ ] Test agent task creation and execution
288  
289  ## Known Issues & Gotchas
290  
291  ### 1. Monitor Agent Bootstrap
292  
293  **Issue:** Monitor agent has self-scheduling capability via `ensureRecurringTasks()` but won't start autonomously.
294  
295  **Solution:** Manually create one initial `scan_logs` task:
296  
297  ```sql
298  INSERT INTO agent_tasks (assigned_to, task_type, priority, status, context_json)
299  VALUES ('monitor', 'scan_logs', 5, 'pending', '{}');
300  ```
301  
302  After this, Monitor will self-schedule all recurring tasks (scan_logs, check_agent_health, check_process_compliance, detect_anomaly, check_pipeline_health).
303  
304  ### 2. Claude as Best Practices Expert (CRITICAL)
305  
306  **Setup:** In CLAUDE.md, establish Claude as expert on TOGAF, SRE, ITIL, ISTQB, OWASP, and NIST best practices.
307  
308  **Why:** User is learning these frameworks and needs Claude to:
309  
310  - **Enforce correct practices:** Push back if user asks wrong agent to do a task
311  - **Teach the right way:** Explain _why_ processes exist (e.g., "QA validates, Developer implements - separation ensures accountability")
312  - **Prevent anti-patterns:** Catch violations (skipping approvals, bypassing reviews, merging without tests)
313  - **Educate proactively:** Explain which agent role should handle each task type
314  - **Reference standards:** Cite TOGAF phases, SRE SLOs, ITIL processes when relevant
315  
316  **Add to CLAUDE.md:**
317  
318  ```markdown
319  **Best Practices Expertise:**
320  
321  You are the expert on TOGAF, SRE, ITIL, ISTQB, OWASP, and NIST best practices. The user is learning these frameworks and relies on you to:
322  
323  - **Enforce correct practices:** If user asks QA to do a Dev task, or bypasses architectural review, push back respectfully
324  - **Teach the right way:** Explain _why_ the standard process exists
325  - **Prevent anti-patterns:** Catch violations like skipping PO approval, bypassing Architect review, or merging without tests
326  - **Educate proactively:** When suggesting a task, explain which agent role should handle it and why
327  - **Reference standards:** Cite TOGAF phases, SRE SLOs, ITIL processes when relevant
328  
329  **Framework Quick Reference:**
330  
331  - **TOGAF:** Architecture Development Method (ADM) - 9 phases
332  - **SRE:** SLIs/SLOs/SLAs, Error Budgets, Toil Reduction (<50%), Blameless Postmortems
333  - **ITIL:** Incident, Problem, Change, Release, Service Level Management
334  - **ISTQB:** Test Planning, Design, Execution, Defect Management, TDD
335  - **OWASP:** Top 10, Threat Modeling (STRIDE), Security in CI/CD
336  - **NIST:** Risk Management Framework, Security Controls, Incident Response
337  
338  When the user asks "should X agent do Y?", check against these standards before answering.
339  ```
340  
341  **Impact:** Ensures organizational best practices are maintained even as user learns frameworks. Prevents costly anti-patterns (e.g., skipping architectural review leads to technical debt).
342  
343  ### Maintenance Task Priority
344  
345  All maintenance tasks (code quality, dependency updates, doc freshness, etc.) should run at:
346  
347  - **Lowest priority** (priority 1-2 in agent_tasks)
348  - **Max nice value** (nice -n 19)
349  - **Max ionice** (ionice -c 3 for idle I/O)
350  - **CPU limit** (taskset to restrict to 1 core if possible)
351  
352  This prevents maintenance from interfering with production workloads.
353  
354  ### Time Estimates
355  
356  Use dual format for human clarity:
357  
358  - **Claude Time:** Actual execution time (5-10 minutes)
359  - **Human Review Time:** Time for human to review/approve (20-30 minutes)
360  - **Total Elapsed Time:** Include tests, approvals, iterations (2-4 hours)
361  
362  Example: "Docs restructuring - Claude: 10min | Review: 30min | Total: 2hr"
363  
364  ### Git Hooks Performance
365  
366  Use lint-staged to only process staged files, not entire codebase:
367  
368  - Before: 120s commit time (full codebase)
369  - After: 2-5s commit time (staged files only)
370  
371  See `package.json` lint-staged configuration.
372  
373  ## Maintenance
374  
375  This document should be updated whenever:
376  
377  - New reusable patterns are established
378  - Agent system architecture changes
379  - Testing infrastructure evolves
380  - Known issues are discovered/resolved
381  - Bootstrap procedures change
382  
383  ## Future Enhancements
384  
385  Components planned for future reusability:
386  
387  - [ ] Jira/ticketing system integration
388  - [ ] Distributed agent system (PostgreSQL + Redis)
389  - [ ] Mobile integration (WebSocket + Claude Android)
390  - [ ] CodeClaw integration for high-level planning
391  - [ ] Architectural workflow enforcement
392  - [ ] SLO tracking and alerting
393  - [ ] Automated security scanning (Snyk, Semgrep)
394  
395  Last updated: 2026-02-15