@plures/praxis 1.2.13 → 1.2.41

package/docs/DOGFOODING_INDEX.md

@@ -0,0 +1,169 @@
+# Dogfooding Plures Tools - Complete Guide
+
+This is the master index for all dogfooding documentation in the Praxis repository.
+
+## 🚀 Getting Started
+
+**New to dogfooding?** Start here:
+
+1. **[Dogfooding Quick Start](./DOGFOODING_QUICK_START.md)** - Get up and running in 5 minutes
+2. **[Plures Tools Inventory](./PLURES_TOOLS_INVENTORY.md)** - See what tools are available
+3. **[Workflow Example](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md)** - See dogfooding in action
+
+## 📚 Core Documentation
+
+### Daily Workflow
+- **[Dogfooding Checklist](./DOGFOODING_CHECKLIST.md)** - Daily, weekly, and monthly checklists
+  - Before starting work
+  - During development
+  - Before committing
+  - Weekly reviews
+  - Monthly assessments
+
+### Tool Information
+- **[Plures Tools Inventory](./PLURES_TOOLS_INVENTORY.md)** - Complete list of all Plures tools
+  - Current adoption status
+  - Usage examples
+  - Adoption priorities
+  - Integration status summary
+
+### Decision Ledger Specific
+- **[Decision Ledger Dogfooding](./decision-ledger/DOGFOODING.md)** - Contract-specific workflow
+  - Contract creation and validation
+  - Ledger snapshot management
+  - CI integration
+
+## 🎯 Practical Examples
+
+- **[End-to-End Workflow Example](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md)** - Complete example of dogfooding all tools when adding a feature
+
+## 🐛 Reporting Friction
+
+### Issue Templates
+- **Dogfooding Friction Report** - Use when you encounter friction with any Plures tool
+  - Located at: `.github/ISSUE_TEMPLATE/dogfooding.yml`
+  - Auto-tagged with `dogfood` label
+  - Focus on one friction point per issue
+
+### When to File
+File immediately when you encounter:
+- Confusing error messages
+- Missing/unclear documentation
+- Manual steps that should be automated
+- Unexpected behavior
+- Performance issues
+
+### How to File
+1. Go to [Issues → New Issue](https://github.com/plures/praxis/issues/new/choose)
+2. Select **Dogfooding Friction Report**
+3. Fill out the template
+4. Submit
+
+## 🔧 Available Tools
+
+| Tool | Status | Docs | Priority |
+|------|--------|------|----------|
+| Praxis CLI | ✅ Adopted | [README](../README.md#cli-npx-friendly) | Maintain |
+| PluresDB | ✅ Adopted | [README](../README.md#pluresdb-integration) | Expand |
+| Decision Ledger | ✅ Adopted | [Dogfooding](./decision-ledger/DOGFOODING.md) | Maintain |
+| Unum | ⚠️ Partial | [README](../README.md#unified-workflow-example) | Expand |
+| State-Docs | ⚠️ Partial | [README](../README.md#unified-workflow-example) | **High** |
+| CodeCanvas | ⚠️ Available | [README](../README.md#unified-workflow-example) | **High** |
+| OpenClaw | ❌ Not Adopted | - | Research |
+
+## 📋 Quick Reference
+
+### Essential Commands
+```bash
+# Build and validate
+npm run build
+npm run validate:contracts
+npm run scan:rules
+
+# Testing
+npm test
+npm run typecheck
+
+# CLI usage
+npx praxis --help
+npx praxis create app my-app
+npx praxis generate --schema src/schemas/app.schema.ts
+```
+
+### Key Directories
+```
+docs/
+├── DOGFOODING_QUICK_START.md          # Start here
+├── DOGFOODING_CHECKLIST.md            # Daily/weekly/monthly tasks
+├── PLURES_TOOLS_INVENTORY.md          # All available tools
+├── decision-ledger/
+│   └── DOGFOODING.md                  # Decision Ledger workflow
+└── examples/
+    ├── README.md                      # Examples index
+    └── DOGFOODING_WORKFLOW_EXAMPLE.md # Complete workflow
+
+.github/ISSUE_TEMPLATE/
+└── dogfooding.yml                      # Friction report template
+```
+
+## 🎓 Learning Path
+
+### Week 1: Foundation
+1. Read [Quick Start](./DOGFOODING_QUICK_START.md)
+2. Review [Tools Inventory](./PLURES_TOOLS_INVENTORY.md)
+3. Follow [Daily Checklist](./DOGFOODING_CHECKLIST.md#daily-development-workflow)
+4. File at least one friction report
+
+### Week 2: Practice
+1. Try the [Workflow Example](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md)
+2. Use CodeCanvas to visualize a schema
+3. Use State-Docs to generate documentation
+4. Complete [Weekly Review](./DOGFOODING_CHECKLIST.md#weekly-review-friday-or-end-of-sprint)
+
+### Week 3: Integration
+1. Integrate Praxis CLI into your workflow
+2. Use PluresDB for test fixtures
+3. Adopt contract-first development
+4. Complete [Monthly Assessment](./DOGFOODING_CHECKLIST.md#monthly-assessment-first-week-of-month)
+
+### Week 4+: Mastery
+1. Dogfood all tools by default
+2. File friction reports proactively
+3. Help others adopt dogfooding
+4. Contribute improvements back
+
+## 🤝 Contributing
+
+Found a gap in the documentation? Have a great dogfooding pattern to share?
+
+1. File a friction report if documentation is unclear
+2. Add examples to `docs/examples/`
+3. Update the [Tools Inventory](./PLURES_TOOLS_INVENTORY.md) with new learnings
+4. Share your workflow in team discussions
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for full guidelines.
+
+## 📊 Success Metrics
+
+You're successfully dogfooding when:
+- ✅ You use Praxis CLI regularly for validation and generation
+- ✅ You define contracts before implementing rules
+- ✅ You file friction reports when you encounter problems
+- ✅ You complete weekly reviews
+- ✅ You help others adopt dogfooding practices
+
+## 🔗 Related Resources
+
+- [Main README](../README.md)
+- [Contributing Guidelines](../CONTRIBUTING.md)
+- [Decision Ledger Behavior Ledger](./decision-ledger/BEHAVIOR_LEDGER.md)
+- [GitHub Issue Templates](../.github/ISSUE_TEMPLATE/)
+
+---
+
+**Remember:** Dogfooding is about **using** our tools, **observing** friction, and **reporting** issues. Every friction report makes our tools better! 🚀
+
+---
+
+Last Updated: 2026-02-01  
+Maintainer: Praxis Core Team

package/docs/DOGFOODING_QUICK_START.md

@@ -0,0 +1,140 @@
+# Dogfooding Plures Tools - Quick Start
+
+This guide helps you start dogfooding Plures tools immediately.
+
+## What is Dogfooding?
+
+**Dogfooding** = Using our own tools in daily development and filing issues when we find friction.
+
+**Goal**: Find and fix problems before users encounter them.
+
+## 🚀 Quick Start (5 minutes)
+
+### 1. Review Available Tools
+
+See what tools you can use: [`docs/PLURES_TOOLS_INVENTORY.md`](./PLURES_TOOLS_INVENTORY.md)
+
+**High Priority for Adoption:**
+- ✅ **Praxis CLI** - Already using it
+- ⚠️ **State-Docs** - Should use for documentation
+- ⚠️ **CodeCanvas** - Should use for visualization
+
+### 2. Follow the Daily Checklist
+
+When developing, follow the quick checklist in [`docs/DOGFOODING_CHECKLIST.md`](./DOGFOODING_CHECKLIST.md):
+
+**Before Starting:**
+```bash
+git pull origin main
+npm run build
+npm run validate:contracts
+```
+
+**When Adding/Modifying Rules:**
+1. Define contract with `defineContract()`
+2. Attach to rule via `meta.contract`
+3. Write tests for all examples
+4. Run `npm run scan:rules` and `npm run validate:contracts`
+
+**When You Find Friction:**
+- File issue immediately using the **Dogfooding Friction Report** template
+- One friction point per issue
+- Tag with `dogfood` label
+
+### 3. Try a Tool Today
+
+Pick one tool to try this week:
+
+**Option A: Visualize a Schema with CodeCanvas**
+```typescript
+import { schemaToCanvas } from '@plures/praxis';
+const canvas = schemaToCanvas(mySchema);
+// Friction? File an issue!
+```
+
+**Option B: Generate Docs with State-Docs**
+```typescript
+import { createStateDocsGenerator } from '@plures/praxis';
+const docsGen = createStateDocsGenerator({
+  projectTitle: 'My Module',
+  target: './docs'
+});
+// Friction? File an issue!
+```
+
+**Option C: Use Praxis CLI for Generation**
+```bash
+npx praxis generate --schema src/schemas/my-schema.ts
+# Friction? File an issue!
+```
+
+## 📋 Filing Friction Reports
+
+### When to File
+
+File **immediately** when you encounter:
+- Confusing error messages
+- Missing documentation
+- Manual steps that should be automated
+- Unexpected behavior
+- Performance issues
+
+### How to File
+
+1. Go to [Issues → New Issue](https://github.com/plures/praxis/issues/new/choose)
+2. Select **Dogfooding Friction Report**
+3. Fill out the template (focus on ONE friction point)
+4. Submit with `dogfood` label
+
+### Example Good Issues
+
+✅ "Praxis CLI `validate` command doesn't show file path for missing contracts"  
+✅ "State-Docs requires manual config - should auto-detect schema files"  
+✅ "CodeCanvas export example missing for nested object schemas"
+
+❌ "Validation is confusing" (too vague)  
+❌ "Documentation needs work" (too broad)
+
+## 🔄 Weekly Review
+
+Every Friday (or end of sprint):
+
+1. **Check your tool usage**: What tools did you use this week?
+2. **Identify gaps**: What could you have used but didn't?
+3. **Review filed issues**: Are they tagged and actionable?
+
+See full checklist: [`docs/DOGFOODING_CHECKLIST.md#weekly-review-friday-or-end-of-sprint`](./DOGFOODING_CHECKLIST.md#weekly-review-friday-or-end-of-sprint)
+
+## 📚 Resources
+
+| Resource | Purpose |
+|----------|---------|
+| [`PLURES_TOOLS_INVENTORY.md`](./PLURES_TOOLS_INVENTORY.md) | List of all tools and adoption status |
+| [`DOGFOODING_CHECKLIST.md`](./DOGFOODING_CHECKLIST.md) | Daily/weekly/monthly checklists |
+| [`decision-ledger/DOGFOODING.md`](./decision-ledger/DOGFOODING.md) | Decision Ledger specific workflow |
+| [`.github/ISSUE_TEMPLATE/dogfooding.yml`](../.github/ISSUE_TEMPLATE/dogfooding.yml) | Issue template for friction reports |
+| [`CONTRIBUTING.md`](../CONTRIBUTING.md) | Full contributing guidelines |
+
+## 🎯 This Week's Focus
+
+**High-Priority Tools to Adopt:**
+1. **CodeCanvas** - Visualize at least one complex schema
+2. **State-Docs** - Generate docs for at least one module
+3. **Praxis CLI** - Use for generation instead of manual coding
+
+**Success Metric:** File at least 1-2 dogfooding issues this week.
+
+---
+
+## Need Help?
+
+- Check the [Plures Tools Inventory](./PLURES_TOOLS_INVENTORY.md) for tool documentation
+- Review examples in the `examples/` directory
+- Ask in discussions or file a question issue
+
+**Remember:** Finding friction is success! Every friction report makes the tools better.
+
+---
+
+Last Updated: 2026-02-01  
+Maintainer: Praxis Core Team