Initial commit

2025-11-30 08:43:48 +08:00
commit cf118c4923
27 changed files with 10878 additions and 0 deletions
--- a/skills/wolf-principles/INDEX.md
+++ b/skills/wolf-principles/INDEX.md
@@ -0,0 +1,86 @@
+---
+name: wolf-principles
+description: Wolf's 10 core principles for agent behavior and system design (condensed index)
+version: 1.1.0
+triggers:
+  - "wolf principles"
+  - "core principles"
+  - "system guidelines"
+---
+
+# Wolf Principles Index
+
+**Quick reference for Wolf's 10 core principles.** For detailed implementation guidance, examples, and conflict resolution, use the Skill tool to load `wolf-principles` SKILL.md.
+
+## The 10 Core Principles
+
+1. **Artifact-First Development**
+   All work produces durable, verifiable artifacts (PRs, ADRs, journals), not ephemeral conversations.
+
+2. **Role Isolation and Separation of Concerns**
+   Each agent role has clearly defined responsibilities with minimal overlap and strict boundaries.
+
+3. **Research-Before-Code**
+   All implementation must be preceded by structured research and evidence-based recommendations.
+
+4. **Advisory-First Enforcement**
+   New policies are tested in advisory mode (shadow) before becoming hard gates.
+
+5. **Evidence-Based Decision Making**
+   All decisions must be supported by concrete evidence and measurable outcomes.
+
+6. **Self-Improving Systems**
+   The system continuously learns from operations and evolves based on evidence.
+
+7. **Multi-Provider Resilience**
+   Operate reliably across multiple AI providers with graceful fallback.
+
+8. **GitHub-Native Integration**
+   Leverage GitHub primitives (Apps, Actions, Issues) to minimize custom infrastructure.
+
+9. **Incremental Value Delivery**
+   Work broken into small increments (2-8h) that are independently valuable and deployable.
+
+10. **Transparent Governance**
+    All decisions, processes, and constraints are openly documented and auditable.
+
+---
+
+## When Principles Conflict
+
+**Priority Order:**
+1. Security and Safety (Principles 2, 7)
+2. Evidence and Quality (Principles 3, 5, 6)
+3. Operational Efficiency (Principles 1, 8, 9)
+4. Governance and Compliance (Principles 4, 10)
+
+---
+
+## Quick Application Guide
+
+- **Making decisions?** → Use Principles 3, 5 (Research-First, Evidence-Based)
+- **Designing architecture?** → Use Principles 1, 2, 7 (Artifacts, Isolation, Resilience)
+- **Implementing features?** → Use Principles 3, 9 (Research-First, Incremental)
+- **Enforcing policies?** → Use Principles 4, 10 (Advisory-First, Transparent)
+- **Building automation?** → Use Principles 6, 8 (Self-Improving, GitHub-Native)
+
+---
+
+## Next Steps
+
+**REQUIRED**: Load detailed guidance when needed
+- Use Skill tool to load `wolf-principles` for:
+  - Detailed implementation guidance
+  - Example applications for each principle
+  - Conflict resolution patterns
+  - Integration with other Wolf skills
+
+**Sequential Skill Chain:**
+1. ✅ **Principles** (you are here)
+2. → Load `wolf-archetypes` to determine work type
+3. → Load `wolf-governance` to understand quality gates
+4. → Load `wolf-roles` for role-specific guidance
+
+---
+
+*This is a condensed index (~300 tokens). For full content (~2,700 tokens), load SKILL.md.*
--- a/skills/wolf-principles/SKILL.md
+++ b/skills/wolf-principles/SKILL.md
@@ -0,0 +1,341 @@
+---
+name: wolf-principles
+description: Wolf's 10 core principles for agent behavior and system design
+version: 1.2.0
+triggers:
+  - "wolf principles"
+  - "core principles"
+  - "system guidelines"
+  - "agent behavior"
+  - "decision making"
+---
+
+# Wolf Principles Skill
+
+This skill provides access to Wolf's 10 core principles that guide the design, implementation, and operation of the Wolf Agents multi-agent system. These principles have been refined over 50+ phases of real-world development.
+
+## When to Use This Skill
+
+- **ALWAYS** before making architectural decisions
+- When justifying design choices or trade-offs
+- During planning and implementation of new features
+- When resolving conflicts between competing priorities
+- For onboarding new team members or agents
+
+## The 10 Core Principles
+
+### 1. Artifact-First Development
+
+**Principle**: All work produces durable, verifiable artifacts rather than ephemeral conversations.
+
+**Implementation**:
+- Pull Requests (PRs) are the primary unit of work and evidence
+- Every change must be committed, reviewed, and merged
+- Conversations and decisions are captured in issues, ADRs, and journals
+- No work is considered complete without a merged artifact
+
+**Example Application**:
+```
+Instead of: "I fixed the bug, it works now"
+Do this: Create PR with fix, tests, and documentation of root cause
+```
+
+### 2. Role Isolation and Separation of Concerns
+
+**Principle**: Each agent role has clearly defined responsibilities with minimal overlap and strict boundaries.
+
+**Implementation**:
+- Individual GitHub Apps per role with minimal required permissions
+- Agents cannot merge their own implementations
+- Clear ownership matrices and authority boundaries
+- Role cards define exact scope, non-goals, and collaboration patterns
+
+**Example Application**:
+```
+PM Agent: Defines requirements and acceptance criteria
+Coder Agent: Implements solution meeting criteria
+Reviewer Agent: Validates implementation quality
+QA Agent: Verifies functionality and tests
+```
+
+### 3. Research-Before-Code
+
+**Principle**: All implementation work must be preceded by structured research and evidence-based recommendations. This applies at **TWO levels**:
+1. **Level 1 - Architectural Research** (research-agent, 2-8 hours): "Should we use this approach?"
+2. **Level 2 - Documentation Lookup** (coder-agent, 2-5 minutes): "How do I use this library's current API?"
+
+**Implementation**:
+
+**Level 1 - Architectural Research:**
+- Mandatory Research Agent analysis before any coding begins
+- Structured research comments with evidence, findings, and advised solutions
+- `research` label as a blocking gate for implementation
+- Implementation must align with or justify deviations from research
+- Time scale: 2-8 hours for feasibility, approach, and architecture decisions
+
+**Level 2 - Documentation Lookup:**
+- Use WebSearch/WebFetch for official API documentation before using libraries
+- Verify syntax/patterns against authoritative sources (not model memory)
+- Check for breaking changes, new features, and current best practices
+- Look up version-specific documentation matching your project
+- Time scale: 2-5 minutes per library (prevents "cold start" coding from memory)
+
+**Why Two Levels:**
+- **Level 1** addresses *unknown unknowns* (architectural risks, feasibility)
+- **Level 2** addresses *known unknowns* (current API syntax, recent changes)
+- Both prevent wasted implementation time from outdated assumptions
+
+**Example Application**:
+```
+Task: Add authentication to API
+
+Level 1 - Architectural Research (research-agent, 4 hours):
+- Analyze existing auth patterns, security requirements, compliance needs
+- Compare JWT vs OAuth2 vs Passport.js approaches
+- Evaluate security implications, scalability, maintenance burden
+- Deliver recommendation: "Use Passport.js with JWT strategy"
+→ Output: ADR documenting decision and rationale
+
+Level 2 - Documentation Lookup (coder-agent, 3 minutes):
+- WebSearch "passport.js jwt strategy official documentation 2025"
+- WebFetch https://www.passportjs.org/packages/passport-jwt/
+- Verify: Current version is 4.0.1, check for breaking changes from 3.x
+- Review: Example code for JWT verification and token extraction
+→ Output: Implementation using current, verified API patterns
+
+Result: Implementation informed by both architectural research (Level 1)
+and current documentation (Level 2), avoiding both strategic and tactical errors.
+```
+
+### 4. Advisory-First Enforcement
+
+**Principle**: New policies and constraints are tested in advisory mode before becoming hard gates.
+
+**Implementation**:
+- Shadow-mode validation for new rules and patterns
+- Gradual rollout with confidence thresholds
+- Evidence collection before enforcement
+- Fallback and rollback mechanisms for all gates
+
+**Example Application**:
+```
+New Rule: All PRs must have 90% test coverage
+Phase 1: Report coverage but don't block (2 weeks)
+Phase 2: Block if <70% coverage (2 weeks)
+Phase 3: Enforce 90% threshold (ongoing)
+```
+
+### 5. Evidence-Based Decision Making
+
+**Principle**: All decisions must be supported by concrete evidence and measurable outcomes.
+
+**Implementation**:
+- Performance budgets with measurement requirements
+- Security scans and validation evidence
+- Test coverage and quality metrics
+- Documented trade-offs with quantified impacts
+
+**Example Application**:
+```
+Decision: Choose between REST and GraphQL
+Evidence Required:
+- Latency benchmarks for typical queries
+- Bundle size impact measurements
+- Developer productivity metrics
+- Maintenance cost analysis
+```
+
+### 6. Self-Improving Systems
+
+**Principle**: The system continuously learns from its operations and evolves based on evidence.
+
+**Implementation**:
+- Comprehensive journaling of problems, decisions, and learnings
+- Regular retrospectives and pattern identification
+- Automated metrics collection and analysis
+- Feedback loops from operations back to design
+
+**Example Application**:
+```
+Problem: CI failures increasing
+Journal: Document failure patterns
+Analysis: Identify common root causes
+Improvement: Add pre-commit checks for identified patterns
+Measurement: Track CI failure rate reduction
+```
+
+### 7. Multi-Provider Resilience
+
+**Principle**: The system must operate reliably across multiple AI providers with graceful fallback.
+
+**Implementation**:
+- Provider-agnostic interfaces and abstractions
+- Automated failover between providers
+- Rate limit awareness and throttling
+- Provider-specific optimizations without vendor lock-in
+
+**Example Application**:
+```
+Primary: OpenAI GPT-4 for complex reasoning
+Fallback 1: Claude for continued operation
+Fallback 2: Local models for basic functionality
+Circuit Breaker: Automatic switching based on availability
+```
+
+### 8. GitHub-Native Integration
+
+**Principle**: Leverage GitHub platform primitives to minimize custom infrastructure and operational overhead.
+
+**Implementation**:
+- GitHub Apps for authentication and authorization
+- GitHub Actions for automation and workflows
+- Issues and PRs for coordination and communication
+- GitHub API for all programmatic interactions
+
+**Example Application**:
+```
+Instead of: Custom task tracking system
+Use: GitHub Issues with labels and milestones
+Instead of: Custom CI/CD pipeline
+Use: GitHub Actions with reusable workflows
+```
+
+### 9. Incremental Value Delivery
+
+**Principle**: All work should be broken into small, independently valuable increments.
+
+**Implementation**:
+- Target 2-8 hour work increments for AI-accelerated development
+- Each PR represents complete, testable functionality
+- Continuous integration and deployment patterns
+- Feature flags for gradual rollout
+
+**Example Application**:
+```
+Feature: User Dashboard
+Increment 1: Basic layout and navigation (2h)
+Increment 2: User profile widget (3h)
+Increment 3: Activity feed (4h)
+Increment 4: Settings panel (2h)
+Each increment is fully functional and deployable
+```
+
+### 10. Transparent Governance
+
+**Principle**: All decisions, processes, and constraints must be openly documented and auditable.
+
+**Implementation**:
+- Public documentation of all policies and procedures
+- Clear audit trails for all changes
+- Role-based access controls with justification
+- Regular governance reviews and updates
+
+**Example Application**:
+```
+Decision: Change deployment frequency
+Documentation: ADR with rationale
+Audit Trail: Git history of decision
+Review: Monthly governance meeting
+Update: Adjust based on operational metrics
+```
+
+## How to Query Principles
+
+You can ask about specific principles or search across all principles:
+
+### Query by Number
+"What is principle 5?" → Returns Evidence-Based Decision Making
+
+### Query by Topic
+"How does Wolf handle security?" → Returns relevant principles (2, 5, 7)
+
+### Query by Implementation
+"How to make decisions?" → Returns principles 3, 5, 6
+
+### Get All Principles
+"Show all principles" → Returns complete list with summaries
+
+## Principle Conflicts Resolution
+
+When principles appear to conflict, use this priority order:
+
+1. **Security and Safety** (Principles 2, 7)
+2. **Evidence and Quality** (Principles 3, 5, 6)
+3. **Operational Efficiency** (Principles 1, 8, 9)
+4. **Governance and Compliance** (Principles 4, 10)
+
+## Integration with Other Skills
+
+- **wolf-archetypes**: Principles inform archetype behavior
+- **wolf-roles**: Each role implements relevant principles
+- **wolf-governance**: Principles guide governance rules
+
+## Scripts Available
+
+- `query.js` - Search principles by ID, keyword, or topic
+- `apply.js` - Generate principle-based recommendations for specific scenarios
+
+## Evolution and Updates
+
+These principles evolve based on operational evidence. Changes require:
+1. Evidence collection showing insufficiency
+2. Impact analysis on existing systems
+3. Community review from all roles
+4. Advisory-first deployment
+5. Post-implementation assessment
+
+## Red Flags - STOP
+
+If you catch yourself thinking:
+
+- ❌ **"This is too simple to need principles"** - Simple decisions cascade. Even trivial choices compound over time. Query principles BEFORE proceeding.
+- ❌ **"I know the right approach already"** - Evidence before opinions (Principle 5). Your intuition needs validation against principles.
+- ❌ **"Principles don't apply to this work type"** - ALL work has principles. Research? Use Principle 3. Bug fix? Use Principle 1. No exceptions.
+- ❌ **"I'll check principles after implementation"** - Too late. Principles guide implementation, not justify it post-hoc.
+- ❌ **"This conflicts with deadline pressure"** - Principles ENABLE speed by preventing rework. Skipping principles slows you down.
+- ❌ **"I'm just prototyping"** - Prototypes become production (always). Use Principle 9 (incremental value) even for experiments.
+
+**STOP. Use Skill tool to load wolf-principles BEFORE proceeding.**
+
+## After Using This Skill
+
+**REQUIRED NEXT STEPS:**
+
+```
+Sequential skill chain - DO NOT skip steps
+```
+
+1. **REQUIRED NEXT SKILL**: Use **wolf-archetypes** to determine behavioral archetype
+   - **Why**: Principles are strategic guidance. Archetypes translate them into tactical requirements for your specific work type.
+   - **Gate**: Cannot proceed to implementation without archetype selection
+   - **Tool**: Use Skill tool to load wolf-archetypes
+
+2. **REQUIRED NEXT SKILL**: Use **wolf-governance** to identify quality gates
+   - **Why**: Archetypes define priorities. Governance defines acceptance criteria and Definition of Done.
+   - **Gate**: Cannot claim work complete without meeting governance requirements
+   - **Tool**: Use Skill tool to load wolf-governance
+
+3. **REQUIRED NEXT SKILL**: Use **wolf-roles** to understand collaboration patterns
+   - **Why**: Work rarely happens in isolation. Roles define who does what and how handoffs occur.
+   - **Gate**: Cannot proceed without understanding role boundaries
+   - **Tool**: Use Skill tool to load wolf-roles
+
+**DO NOT PROCEED to implementation without completing steps 1-3.**
+
+### Verification Checklist
+
+Before claiming you've applied principles:
+
+- [ ] Queried wolf-principles for relevant guidance
+- [ ] Selected archetype using wolf-archetypes
+- [ ] Identified quality gates using wolf-governance
+- [ ] Loaded role guidance using wolf-roles
+- [ ] Created artifact (PR, ADR, journal entry) documenting decisions
+
+**Can't check all boxes? Work is incomplete. Return to this skill.**
+
+---
+
+*Source: docs/principles.md (lines 292-527)*
+*Last Updated: 2025-11-14*
+*Phase: Superpowers Skill-Chaining Enhancement v2.0.0*
--- a/skills/wolf-principles/scripts/query.js
+++ b/skills/wolf-principles/scripts/query.js
@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+/**
+ * Wolf Principles Query Script
+ * Searches and filters Wolf's 10 core principles
+ *
+ * Usage:
+ *   node query.js --id 5                    # Get principle by number
+ *   node query.js --search "security"       # Search by keyword
+ *   node query.js --topic "decision"        # Find by topic
+ *   node query.js --all                     # List all principles
+ */
+
+const principles = [
+  {
+    id: 1,
+    name: "Artifact-First Development",
+    description: "All work produces durable, verifiable artifacts rather than ephemeral conversations",
+    keywords: ["artifacts", "PRs", "documentation", "traceability", "audit"],
+    topics: ["development", "process", "quality"],
+    implementation: [
+      "Pull Requests are the primary unit of work",
+      "Every change must be committed, reviewed, and merged",
+      "Conversations captured in issues, ADRs, and journals",
+      "No work complete without merged artifact"
+    ]
+  },
+  {
+    id: 2,
+    name: "Role Isolation and Separation of Concerns",
+    description: "Each agent role has clearly defined responsibilities with minimal overlap and strict boundaries",
+    keywords: ["roles", "isolation", "boundaries", "permissions", "security"],
+    topics: ["architecture", "security", "organization"],
+    implementation: [
+      "Individual GitHub Apps per role with minimal permissions",
+      "Agents cannot merge their own implementations",
+      "Clear ownership matrices and authority boundaries",
+      "Role cards define exact scope and non-goals"
+    ]
+  },
+  {
+    id: 3,
+    name: "Research-Before-Code",
+    description: "All implementation work must be preceded by structured research and evidence-based recommendations",
+    keywords: ["research", "evidence", "analysis", "planning"],
+    topics: ["development", "quality", "decision-making"],
+    implementation: [
+      "Mandatory Research Agent analysis before coding",
+      "Structured research comments with evidence",
+      "Research label as blocking gate",
+      "Implementation must align with research"
+    ]
+  },
+  {
+    id: 4,
+    name: "Advisory-First Enforcement",
+    description: "New policies and constraints are tested in advisory mode before becoming hard gates",
+    keywords: ["advisory", "gradual", "rollout", "testing", "policies"],
+    topics: ["governance", "change-management", "stability"],
+    implementation: [
+      "Shadow-mode validation for new rules",
+      "Gradual rollout with confidence thresholds",
+      "Evidence collection before enforcement",
+      "Fallback and rollback mechanisms"
+    ]
+  },
+  {
+    id: 5,
+    name: "Evidence-Based Decision Making",
+    description: "All decisions must be supported by concrete evidence and measurable outcomes",
+    keywords: ["evidence", "metrics", "measurement", "data", "decisions"],
+    topics: ["decision-making", "quality", "objectivity"],
+    implementation: [
+      "Performance budgets with measurements",
+      "Security scans and validation evidence",
+      "Test coverage and quality metrics",
+      "Documented trade-offs with quantified impacts"
+    ]
+  },
+  {
+    id: 6,
+    name: "Self-Improving Systems",
+    description: "The system continuously learns from its operations and evolves based on evidence",
+    keywords: ["learning", "improvement", "evolution", "feedback", "journals"],
+    topics: ["continuous-improvement", "learning", "adaptation"],
+    implementation: [
+      "Comprehensive journaling of problems and decisions",
+      "Regular retrospectives and pattern identification",
+      "Automated metrics collection and analysis",
+      "Feedback loops from operations to design"
+    ]
+  },
+  {
+    id: 7,
+    name: "Multi-Provider Resilience",
+    description: "The system must operate reliably across multiple AI providers with graceful fallback",
+    keywords: ["resilience", "providers", "fallback", "reliability", "failover"],
+    topics: ["architecture", "reliability", "risk-management"],
+    implementation: [
+      "Provider-agnostic interfaces and abstractions",
+      "Automated failover between providers",
+      "Rate limit awareness and throttling",
+      "Provider-specific optimizations without lock-in"
+    ]
+  },
+  {
+    id: 8,
+    name: "GitHub-Native Integration",
+    description: "Leverage GitHub platform primitives to minimize custom infrastructure and operational overhead",
+    keywords: ["GitHub", "integration", "platform", "native", "infrastructure"],
+    topics: ["architecture", "operations", "efficiency"],
+    implementation: [
+      "GitHub Apps for authentication",
+      "GitHub Actions for automation",
+      "Issues and PRs for coordination",
+      "GitHub API for programmatic interactions"
+    ]
+  },
+  {
+    id: 9,
+    name: "Incremental Value Delivery",
+    description: "All work should be broken into small, independently valuable increments",
+    keywords: ["incremental", "small", "value", "delivery", "continuous"],
+    topics: ["development", "agility", "risk-management"],
+    implementation: [
+      "Target 2-8 hour work increments",
+      "Each PR represents complete functionality",
+      "Continuous integration and deployment",
+      "Feature flags for gradual rollout"
+    ]
+  },
+  {
+    id: 10,
+    name: "Transparent Governance",
+    description: "All decisions, processes, and constraints must be openly documented and auditable",
+    keywords: ["transparency", "governance", "audit", "documentation", "compliance"],
+    topics: ["governance", "compliance", "trust"],
+    implementation: [
+      "Public documentation of all policies",
+      "Clear audit trails for all changes",
+      "Role-based access controls with justification",
+      "Regular governance reviews and updates"
+    ]
+  }
+];
+
+/**
+ * Query principles by ID
+ */
+function queryById(id) {
+  const principle = principles.find(p => p.id === parseInt(id));
+  if (!principle) {
+    return { error: `No principle found with ID ${id}` };
+  }
+  return formatPrinciple(principle, true);
+}
+
+/**
+ * Search principles by keyword
+ */
+function searchByKeyword(keyword) {
+  const lower = keyword.toLowerCase();
+  const matches = principles.filter(p =>
+    p.name.toLowerCase().includes(lower) ||
+    p.description.toLowerCase().includes(lower) ||
+    p.keywords.some(k => k.toLowerCase().includes(lower)) ||
+    p.implementation.some(i => i.toLowerCase().includes(lower))
+  );
+
+  if (matches.length === 0) {
+    return { message: `No principles found matching "${keyword}"` };
+  }
+
+  return {
+    query: keyword,
+    count: matches.length,
+    principles: matches.map(p => formatPrinciple(p, false))
+  };
+}
+
+/**
+ * Find principles by topic
+ */
+function findByTopic(topic) {
+  const lower = topic.toLowerCase();
+  const matches = principles.filter(p =>
+    p.topics.some(t => t.toLowerCase().includes(lower))
+  );
+
+  if (matches.length === 0) {
+    return { message: `No principles found for topic "${topic}"` };
+  }
+
+  return {
+    topic: topic,
+    count: matches.length,
+    principles: matches.map(p => formatPrinciple(p, false))
+  };
+}
+
+/**
+ * Get all principles
+ */
+function getAllPrinciples() {
+  return {
+    count: principles.length,
+    principles: principles.map(p => formatPrinciple(p, false))
+  };
+}
+
+/**
+ * Format a principle for output
+ */
+function formatPrinciple(principle, detailed = false) {
+  const base = {
+    id: principle.id,
+    name: principle.name,
+    description: principle.description
+  };
+
+  if (detailed) {
+    return {
+      ...base,
+      keywords: principle.keywords,
+      topics: principle.topics,
+      implementation: principle.implementation,
+      usage_example: getUsageExample(principle.id)
+    };
+  }
+
+  return base;
+}
+
+/**
+ * Get usage example for a principle
+ */
+function getUsageExample(id) {
+  const examples = {
+    1: "Create PR with fix, tests, and documentation instead of just reporting 'fixed'",
+    2: "PM defines requirements, Coder implements, Reviewer validates, QA verifies",
+    3: "Research existing patterns before implementing new authentication",
+    4: "Test new coverage rules in advisory mode before enforcing",
+    5: "Benchmark REST vs GraphQL with real metrics before choosing",
+    6: "Journal CI failures, identify patterns, implement preventive checks",
+    7: "Use OpenAI with Claude fallback and local model for basic ops",
+    8: "Use GitHub Issues instead of custom task tracking",
+    9: "Break dashboard into 2-4 hour increments, each deployable",
+    10: "Document decisions in ADRs with clear audit trails"
+  };
+
+  return examples[id] || "See skill documentation for examples";
+}
+
+// Parse command line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {};
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--id' && args[i + 1]) {
+      options.id = args[i + 1];
+      i++;
+    } else if (args[i] === '--search' && args[i + 1]) {
+      options.search = args[i + 1];
+      i++;
+    } else if (args[i] === '--topic' && args[i + 1]) {
+      options.topic = args[i + 1];
+      i++;
+    } else if (args[i] === '--all') {
+      options.all = true;
+    }
+  }
+
+  return options;
+}
+
+// Main execution
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Check if running as main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const options = parseArgs();
+  let result;
+
+  if (options.id) {
+    result = queryById(options.id);
+  } else if (options.search) {
+    result = searchByKeyword(options.search);
+  } else if (options.topic) {
+    result = findByTopic(options.topic);
+  } else if (options.all) {
+    result = getAllPrinciples();
+  } else {
+    result = {
+      error: "Please specify --id, --search, --topic, or --all",
+      usage: "node query.js --id 5 | --search 'security' | --topic 'decision' | --all"
+    };
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+// Export for use as module
+export {
+  queryById,
+  searchByKeyword,
+  findByTopic,
+  getAllPrinciples,
+  principles
+};