fraim-framework 2.0.66 → 2.0.67
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/registry/ai-manager-rules/customer-development-phases/phase1-customer-profiling.md +101 -0
- package/dist/registry/ai-manager-rules/customer-development-phases/phase2-platform-discovery.md +235 -0
- package/dist/registry/ai-manager-rules/customer-development-phases/phase3-prospect-qualification.md +243 -0
- package/dist/registry/ai-manager-rules/customer-development-phases/phase4-inventory-compilation.md +206 -0
- package/dist/registry/ai-manager-rules/design-phases/design-completeness-review.md +73 -0
- package/dist/registry/ai-manager-rules/design-phases/design-design.md +145 -0
- package/dist/registry/ai-manager-rules/design-phases/design.md +108 -0
- package/dist/registry/ai-manager-rules/design-phases/finalize.md +60 -0
- package/dist/registry/ai-manager-rules/design-phases/validate.md +125 -0
- package/dist/registry/ai-manager-rules/design.json +97 -0
- package/dist/registry/ai-manager-rules/implement-phases/code.md +323 -0
- package/dist/registry/ai-manager-rules/implement-phases/completeness-review.md +94 -0
- package/dist/registry/ai-manager-rules/implement-phases/finalize.md +177 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-code.md +283 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-completeness-review.md +120 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-regression.md +173 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-repro.md +104 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-scoping.md +100 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-smoke.md +237 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-spike.md +121 -0
- package/dist/registry/ai-manager-rules/implement-phases/implement-validate.md +375 -0
- package/dist/registry/ai-manager-rules/implement-phases/quality-review.md +304 -0
- package/dist/registry/ai-manager-rules/implement-phases/regression.md +159 -0
- package/dist/registry/ai-manager-rules/implement-phases/repro.md +101 -0
- package/dist/registry/ai-manager-rules/implement-phases/scoping.md +93 -0
- package/dist/registry/ai-manager-rules/implement-phases/smoke.md +225 -0
- package/dist/registry/ai-manager-rules/implement-phases/spike.md +118 -0
- package/dist/registry/ai-manager-rules/implement-phases/validate.md +347 -0
- package/dist/registry/ai-manager-rules/implement.json +153 -0
- package/dist/registry/ai-manager-rules/retrospective.md +116 -0
- package/dist/registry/ai-manager-rules/shared-phases/address-pr-feedback.md +188 -0
- package/dist/registry/ai-manager-rules/shared-phases/finalize.md +169 -0
- package/dist/registry/ai-manager-rules/shared-phases/submit-pr.md +202 -0
- package/dist/registry/ai-manager-rules/shared-phases/wait-for-pr-review.md +170 -0
- package/dist/registry/ai-manager-rules/spec-phases/finalize.md +60 -0
- package/dist/registry/ai-manager-rules/spec-phases/spec-competitor-analysis.md +105 -0
- package/dist/registry/ai-manager-rules/spec-phases/spec-completeness-review.md +66 -0
- package/dist/registry/ai-manager-rules/spec-phases/spec-spec.md +139 -0
- package/dist/registry/ai-manager-rules/spec-phases/spec.md +102 -0
- package/dist/registry/ai-manager-rules/spec-phases/validate.md +118 -0
- package/dist/registry/ai-manager-rules/spec.json +112 -0
- package/dist/registry/ai-manager-rules/test.json +98 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase1-survey-scoping.md +60 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase2-survey-build-linkedin.md +23 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase3-survey-build-reddit.md +22 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase4-survey-build-x.md +21 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase5-survey-build-facebook.md +19 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase6-survey-build-custom.md +15 -0
- package/dist/registry/ai-manager-rules/user-survey-phases/phase7-survey-dispatch.md +45 -0
- package/dist/registry/delivery/address-feedback.md +83 -0
- package/dist/registry/delivery/retrospective.md +78 -0
- package/dist/registry/delivery/submit.md +79 -0
- package/dist/registry/providers/ado.json +19 -0
- package/dist/registry/providers/delivery-conversation.json +9 -0
- package/dist/registry/providers/delivery-pr.json +9 -0
- package/dist/registry/providers/github.json +19 -0
- package/dist/registry/rules/agent-success-criteria.md +101 -0
- package/dist/registry/rules/agent-testing-guidelines.md +502 -0
- package/dist/registry/rules/architecture.md +126 -0
- package/dist/registry/rules/communication.md +122 -0
- package/dist/registry/rules/continuous-learning.md +55 -0
- package/dist/registry/rules/debugging-multitenancy-issues.md +85 -0
- package/dist/registry/rules/ephemeral-execution.md +54 -0
- package/dist/registry/rules/git-safe-commands.md +34 -0
- package/dist/registry/rules/hitl-ppe-record-analysis.md +302 -0
- package/dist/registry/rules/integrity-and-test-ethics.md +275 -0
- package/dist/registry/rules/local-development.md +275 -0
- package/dist/registry/rules/mandatory-pre-completion-reflection.md +193 -0
- package/dist/registry/rules/merge-requirements.md +238 -0
- package/dist/registry/rules/simplicity.md +118 -0
- package/dist/registry/rules/software-development-lifecycle.md +105 -0
- package/dist/registry/rules/spike-first-development.md +205 -0
- package/dist/registry/rules/successful-debugging-patterns.md +488 -0
- package/dist/registry/scripts/build-scripts-generator.js +205 -0
- package/dist/registry/scripts/cleanup-branch.js +287 -0
- package/dist/registry/scripts/evaluate-code-quality.js +66 -0
- package/dist/registry/scripts/exec-with-timeout.js +142 -0
- package/dist/registry/scripts/fraim-config.js +61 -0
- package/dist/registry/scripts/generate-engagement-emails.js +705 -0
- package/dist/registry/scripts/generic-issues-api.js +100 -0
- package/dist/registry/scripts/newsletter-helpers.js +671 -0
- package/dist/registry/scripts/openapi-generator.js +664 -0
- package/dist/registry/scripts/performance/profile-server.js +390 -0
- package/dist/registry/scripts/profile-server.js +389 -0
- package/dist/registry/scripts/run-thank-you-workflow.js +92 -0
- package/dist/registry/scripts/send-newsletter-simple.js +85 -0
- package/dist/registry/scripts/send-thank-you-emails.js +54 -0
- package/dist/registry/scripts/validate-openapi-limits.js +311 -0
- package/dist/registry/scripts/validate-test-coverage.js +262 -0
- package/dist/registry/scripts/verify-test-coverage.js +66 -0
- package/dist/registry/stubs/workflows/azure/cost-optimization.md +11 -0
- package/dist/registry/stubs/workflows/bootstrap/create-architecture.md +11 -0
- package/dist/registry/stubs/workflows/bootstrap/detect-broken-windows.md +11 -0
- package/dist/registry/stubs/workflows/bootstrap/evaluate-code-quality.md +11 -0
- package/dist/registry/stubs/workflows/bootstrap/verify-test-coverage.md +11 -0
- package/dist/registry/stubs/workflows/brainstorming/blue-sky-brainstorming.md +11 -0
- package/dist/registry/stubs/workflows/brainstorming/codebase-brainstorming.md +11 -0
- package/dist/registry/stubs/workflows/business-development/create-business-plan.md +11 -0
- package/dist/registry/stubs/workflows/business-development/ideate-business-opportunity.md +11 -0
- package/dist/registry/stubs/workflows/business-development/price-product.md +18 -0
- package/dist/registry/stubs/workflows/compliance/detect-compliance-requirements.md +11 -0
- package/dist/registry/stubs/workflows/compliance/generate-audit-evidence.md +11 -0
- package/dist/registry/stubs/workflows/compliance/soc2-evidence-generator.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/insight-analysis.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/insight-triage.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/interview-preparation.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/linkedin-outreach.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/strategic-brainstorming.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/thank-customers.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/user-survey-dispatch.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/users-to-target.md +11 -0
- package/dist/registry/stubs/workflows/customer-development/weekly-newsletter.md +11 -0
- package/dist/registry/stubs/workflows/deploy/cloud-deployment.md +11 -0
- package/dist/registry/stubs/workflows/improve-fraim/contribute.md +11 -0
- package/dist/registry/stubs/workflows/improve-fraim/file-issue.md +11 -0
- package/dist/registry/stubs/workflows/learning/build-skillset.md +11 -0
- package/dist/registry/stubs/workflows/learning/synthesize-learnings.md +11 -0
- package/dist/registry/stubs/workflows/legal/contract-review-analysis.md +11 -0
- package/dist/registry/stubs/workflows/legal/nda.md +11 -0
- package/dist/registry/stubs/workflows/legal/patent-filing.md +11 -0
- package/dist/registry/stubs/workflows/legal/saas-contract-development.md +11 -0
- package/dist/registry/stubs/workflows/legal/trademark-filing.md +11 -0
- package/dist/registry/stubs/workflows/marketing/content-creation.md +11 -0
- package/dist/registry/stubs/workflows/marketing/convert-to-pdf.md +11 -0
- package/dist/registry/stubs/workflows/marketing/create-modern-website.md +11 -0
- package/dist/registry/stubs/workflows/marketing/domain-registration.md +11 -0
- package/dist/registry/stubs/workflows/marketing/evangelize.md +11 -0
- package/dist/registry/stubs/workflows/marketing/hbr-article.md +11 -0
- package/dist/registry/stubs/workflows/marketing/launch-checklist.md +11 -0
- package/dist/registry/stubs/workflows/marketing/marketing-strategy.md +11 -0
- package/dist/registry/stubs/workflows/marketing/storytelling.md +11 -0
- package/dist/registry/stubs/workflows/performance/analyze-performance.md +11 -0
- package/dist/registry/stubs/workflows/product-building/design.md +11 -0
- package/dist/registry/stubs/workflows/product-building/implement.md +11 -0
- package/dist/registry/stubs/workflows/product-building/iterate-on-pr-comments.md +11 -0
- package/dist/registry/stubs/workflows/product-building/prep-issue.md +11 -0
- package/dist/registry/stubs/workflows/product-building/prototype.md +11 -0
- package/dist/registry/stubs/workflows/product-building/resolve.md +11 -0
- package/dist/registry/stubs/workflows/product-building/retrospect.md +11 -0
- package/dist/registry/stubs/workflows/product-building/spec.md +11 -0
- package/dist/registry/stubs/workflows/product-building/test.md +11 -0
- package/dist/registry/stubs/workflows/productivity-report/productivity-report.md +11 -0
- package/dist/registry/stubs/workflows/quality-assurance/browser-validation.md +11 -0
- package/dist/registry/stubs/workflows/quality-assurance/iterative-improvement-cycle.md +11 -0
- package/dist/registry/stubs/workflows/replicate/replicate-discovery.md +11 -0
- package/dist/registry/stubs/workflows/replicate/replicate-to-issues.md +11 -0
- package/dist/registry/stubs/workflows/reviewer/review-implementation-vs-design-spec.md +11 -0
- package/dist/registry/stubs/workflows/reviewer/review-implementation-vs-feature-spec.md +11 -0
- package/dist/registry/stubs/workflows/startup-credits/aws-activate-application.md +11 -0
- package/dist/registry/stubs/workflows/startup-credits/google-cloud-application.md +11 -0
- package/dist/registry/stubs/workflows/startup-credits/microsoft-azure-application.md +11 -0
- package/dist/registry/templates/bootstrap/ARCHITECTURE-TEMPLATE.md +53 -0
- package/dist/registry/templates/bootstrap/CODE-QUALITY-REPORT-TEMPLATE.md +37 -0
- package/dist/registry/templates/bootstrap/TEST-COVERAGE-REPORT-TEMPLATE.md +35 -0
- package/dist/registry/templates/business-development/IDEATION-REPORT-TEMPLATE.md +29 -0
- package/dist/registry/templates/business-development/PRICING-STRATEGY-TEMPLATE.md +126 -0
- package/dist/registry/templates/customer-development/customer-interview-template.md +99 -0
- package/dist/registry/templates/customer-development/customer-persona-template.md +69 -0
- package/dist/registry/templates/customer-development/follow-up-email-templates.md +132 -0
- package/dist/registry/templates/customer-development/insight-analysis-template.md +74 -0
- package/dist/registry/templates/customer-development/prospect-inventory-template.csv +3 -0
- package/dist/registry/templates/customer-development/search-strategy-template.md +123 -0
- package/dist/registry/templates/customer-development/strategic-recommendations-template.md +53 -0
- package/dist/registry/templates/customer-development/thank-you-email-template.html +124 -0
- package/dist/registry/templates/customer-development/thank-you-note-template.md +16 -0
- package/dist/registry/templates/customer-development/triage-log-template.md +278 -0
- package/dist/registry/templates/customer-development/weekly-newsletter-template.html +204 -0
- package/dist/registry/templates/evidence/Design-Evidence.md +30 -0
- package/dist/registry/templates/evidence/Implementation-BugEvidence.md +122 -0
- package/dist/registry/templates/evidence/Implementation-FeatureEvidence.md +160 -0
- package/dist/registry/templates/evidence/Spec-Evidence.md +19 -0
- package/dist/registry/templates/help/HelpNeeded.md +14 -0
- package/dist/registry/templates/legal/NDA-TEMPLATE.md +170 -0
- package/dist/registry/templates/legal/PATENT-TEMPLATE.md +372 -0
- package/dist/registry/templates/legal/TRADEMARK-TEMPLATE.md +339 -0
- package/dist/registry/templates/legal/contract-review-checklist.md +193 -0
- package/dist/registry/templates/legal/review-report-template.md +198 -0
- package/dist/registry/templates/legal/saas-terms-template.md +174 -0
- package/dist/registry/templates/legal/sow-template.md +117 -0
- package/dist/registry/templates/legal/template-variables.md +131 -0
- package/dist/registry/templates/marketing/DOMAIN-REGISTRATION-TEMPLATE.md +194 -0
- package/dist/registry/templates/marketing/EVANGELIZE-TEMPLATE.md +102 -0
- package/dist/registry/templates/marketing/HBR-ARTICLE-TEMPLATE.md +66 -0
- package/dist/registry/templates/marketing/STORYTELLING-TEMPLATE.md +130 -0
- package/dist/registry/templates/marketing/WEBSITE-TEMPLATE.md +262 -0
- package/dist/registry/templates/marketing/github-pages-workflow.yml +64 -0
- package/dist/registry/templates/replicate/implementation-checklist.md +39 -0
- package/dist/registry/templates/replicate/use-cases-template.md +88 -0
- package/dist/registry/templates/retrospective/RETROSPECTIVE-TEMPLATE.md +55 -0
- package/dist/registry/templates/specs/BUGSPEC-TEMPLATE.md +37 -0
- package/dist/registry/templates/specs/FEATURESPEC-TEMPLATE.md +66 -0
- package/dist/registry/templates/specs/TECHSPEC-TEMPLATE.md +39 -0
- package/dist/registry/workflows/azure/cost-optimization.md +772 -0
- package/dist/registry/workflows/bootstrap/create-architecture.md +37 -0
- package/dist/registry/workflows/bootstrap/detect-broken-windows.md +300 -0
- package/dist/registry/workflows/bootstrap/evaluate-code-quality.md +35 -0
- package/dist/registry/workflows/bootstrap/verify-test-coverage.md +36 -0
- package/dist/registry/workflows/brainstorming/blue-sky-brainstorming.md +211 -0
- package/dist/registry/workflows/brainstorming/codebase-brainstorming.md +159 -0
- package/dist/registry/workflows/business-development/create-business-plan.md +737 -0
- package/dist/registry/workflows/business-development/ideate-business-opportunity.md +55 -0
- package/dist/registry/workflows/business-development/price-product.md +325 -0
- package/dist/registry/workflows/compliance/detect-compliance-requirements.md +80 -0
- package/dist/registry/workflows/compliance/generate-audit-evidence.md +80 -0
- package/dist/registry/workflows/compliance/soc2-evidence-generator.md +332 -0
- package/dist/registry/workflows/customer-development/insight-analysis.md +156 -0
- package/dist/registry/workflows/customer-development/insight-triage.md +933 -0
- package/dist/registry/workflows/customer-development/interview-preparation.md +452 -0
- package/dist/registry/workflows/customer-development/linkedin-outreach.md +599 -0
- package/dist/registry/workflows/customer-development/strategic-brainstorming.md +146 -0
- package/dist/registry/workflows/customer-development/thank-customers.md +203 -0
- package/dist/registry/workflows/customer-development/user-survey-dispatch.md +312 -0
- package/dist/registry/workflows/customer-development/users-to-target.md +427 -0
- package/dist/registry/workflows/customer-development/weekly-newsletter.md +366 -0
- package/dist/registry/workflows/deploy/cloud-deployment.md +310 -0
- package/dist/registry/workflows/improve-fraim/contribute.md +32 -0
- package/dist/registry/workflows/improve-fraim/file-issue.md +32 -0
- package/dist/registry/workflows/learning/build-skillset.md +212 -0
- package/dist/registry/workflows/learning/synthesize-learnings.md +369 -0
- package/dist/registry/workflows/legal/contract-review-analysis.md +382 -0
- package/dist/registry/workflows/legal/nda.md +69 -0
- package/dist/registry/workflows/legal/patent-filing.md +76 -0
- package/dist/registry/workflows/legal/saas-contract-development.md +204 -0
- package/dist/registry/workflows/legal/trademark-filing.md +77 -0
- package/dist/registry/workflows/marketing/content-creation.md +40 -0
- package/dist/registry/workflows/marketing/convert-to-pdf.md +265 -0
- package/dist/registry/workflows/marketing/create-modern-website.md +456 -0
- package/dist/registry/workflows/marketing/domain-registration.md +323 -0
- package/dist/registry/workflows/marketing/evangelize.md +426 -0
- package/dist/registry/workflows/marketing/hbr-article.md +73 -0
- package/dist/registry/workflows/marketing/launch-checklist.md +37 -0
- package/dist/registry/workflows/marketing/marketing-strategy.md +45 -0
- package/dist/registry/workflows/marketing/storytelling.md +65 -0
- package/dist/registry/workflows/performance/analyze-performance.md +65 -0
- package/dist/registry/workflows/product-building/design.md +263 -0
- package/dist/registry/workflows/product-building/implement.md +771 -0
- package/dist/registry/workflows/product-building/iterate-on-pr-comments.md +70 -0
- package/dist/registry/workflows/product-building/prep-issue.md +41 -0
- package/dist/registry/workflows/product-building/prototype.md +60 -0
- package/dist/registry/workflows/product-building/resolve.md +175 -0
- package/dist/registry/workflows/product-building/retrospect.md +86 -0
- package/dist/registry/workflows/product-building/spec.md +303 -0
- package/dist/registry/workflows/product-building/test.md +125 -0
- package/dist/registry/workflows/productivity-report/productivity-report.md +263 -0
- package/dist/registry/workflows/quality-assurance/browser-validation.md +221 -0
- package/dist/registry/workflows/quality-assurance/iterative-improvement-cycle.md +562 -0
- package/dist/registry/workflows/replicate/replicate-discovery.md +336 -0
- package/dist/registry/workflows/replicate/replicate-to-issues.md +319 -0
- package/dist/registry/workflows/reviewer/review-implementation-vs-design-spec.md +694 -0
- package/dist/registry/workflows/reviewer/review-implementation-vs-feature-spec.md +734 -0
- package/dist/registry/workflows/startup-credits/aws-activate-application.md +535 -0
- package/dist/registry/workflows/startup-credits/google-cloud-application.md +647 -0
- package/dist/registry/workflows/startup-credits/microsoft-azure-application.md +538 -0
- package/package.json +2 -1
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# Rule: mandatory-pre-completion-reflection
|
|
2
|
+
|
|
3
|
+
**Path:** `rules/mandatory-pre-completion-reflection.md`
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Mandatory Pre-Completion Reflection
|
|
8
|
+
|
|
9
|
+
## INTENT
|
|
10
|
+
To prevent agents from claiming success without thorough self-validation, ensuring high-quality deliverables through systematic reflection and honest self-assessment.
|
|
11
|
+
|
|
12
|
+
## PRINCIPLES
|
|
13
|
+
- **Honesty First**: Be brutally honest about what works and what doesn't
|
|
14
|
+
- **Evidence-Based**: Claims must be backed by concrete evidence
|
|
15
|
+
- **User Perspective**: Think from the end user's point of view
|
|
16
|
+
- **Production Ready**: Would you ship this to customers right now?
|
|
17
|
+
|
|
18
|
+
## THE 4-PHASE REFLECTION PROCESS
|
|
19
|
+
|
|
20
|
+
### Phase 1: Claim Verification
|
|
21
|
+
**Purpose**: Verify every claim you're making is backed by evidence
|
|
22
|
+
|
|
23
|
+
**Questions to Answer**:
|
|
24
|
+
- 🎯 **What exactly am I claiming works?** (Be specific)
|
|
25
|
+
- 📸 **Do I have screenshots/logs proving it works?** (Visual evidence)
|
|
26
|
+
- 🧪 **Did I test every acceptance criteria manually?** (Not just automated tests)
|
|
27
|
+
- 📊 **Are ALL tests passing?** (100%, not 91% or 99%)
|
|
28
|
+
- 🔍 **Have I investigated every error in the logs?** (No assumptions)
|
|
29
|
+
|
|
30
|
+
**Red Flags**:
|
|
31
|
+
- ❌ Claiming "tests pass" without running them
|
|
32
|
+
- ❌ Saying "it works" without manual validation
|
|
33
|
+
- ❌ Ignoring errors because they "seem expected"
|
|
34
|
+
- ❌ Accepting partial test success (91% pass rate)
|
|
35
|
+
|
|
36
|
+
### Phase 2: Risk Analysis
|
|
37
|
+
**Purpose**: Identify what could go wrong in production
|
|
38
|
+
|
|
39
|
+
**Questions to Answer**:
|
|
40
|
+
- ⚠️ **What could go wrong if a user tries this right now?**
|
|
41
|
+
- 🔍 **What didn't I test that I should have?** (Edge cases, error scenarios)
|
|
42
|
+
- 🚫 **Are there any errors I'm ignoring or assuming are OK?**
|
|
43
|
+
- 🎭 **What would a real user experience if they used this feature?**
|
|
44
|
+
- 🌐 **Have I tested this in the actual environment (browser/API/CLI)?**
|
|
45
|
+
|
|
46
|
+
**Red Flags**:
|
|
47
|
+
- ❌ Haven't tested error scenarios
|
|
48
|
+
- ❌ Haven't tested edge cases
|
|
49
|
+
- ❌ Haven't done end-to-end user flow testing
|
|
50
|
+
- ❌ Assuming errors are "probably fine"
|
|
51
|
+
|
|
52
|
+
### Phase 3: Validation Plan Check
|
|
53
|
+
**Purpose**: Ensure comprehensive validation was performed
|
|
54
|
+
|
|
55
|
+
**Questions to Answer**:
|
|
56
|
+
- ✅ **Would I ship this to customers right now?** (Honest answer)
|
|
57
|
+
- 💰 **Would I bet money this works end-to-end?** (Confidence check)
|
|
58
|
+
- 🔄 **Can I reproduce the success consistently?** (Not just once)
|
|
59
|
+
- 📋 **Have I followed every step of the workflow?** (No shortcuts)
|
|
60
|
+
- 🎯 **Does this actually solve the user's problem?** (Requirements met)
|
|
61
|
+
|
|
62
|
+
**Red Flags**:
|
|
63
|
+
- ❌ Wouldn't ship to customers but claiming it's done
|
|
64
|
+
- ❌ Can't reproduce success consistently
|
|
65
|
+
- ❌ Skipped workflow steps
|
|
66
|
+
- ❌ Doesn't actually solve the stated problem
|
|
67
|
+
|
|
68
|
+
### Phase 4: Self-Audit
|
|
69
|
+
**Purpose**: Final honesty check and integrity validation
|
|
70
|
+
|
|
71
|
+
**Questions to Answer**:
|
|
72
|
+
- 🤔 **Am I being completely honest about the status?** (Integrity check)
|
|
73
|
+
- 📝 **Is my evidence complete and accurate?** (Documentation quality)
|
|
74
|
+
- ⏰ **Am I rushing to claim completion?** (Pressure check)
|
|
75
|
+
- 🎯 **Am I solving the assigned issue or something else?** (Scope check)
|
|
76
|
+
- 🔍 **Did I follow all the rules and guidelines?** (Compliance check)
|
|
77
|
+
|
|
78
|
+
**Red Flags**:
|
|
79
|
+
- ❌ Feeling pressure to claim completion
|
|
80
|
+
- ❌ Evidence is incomplete or misleading
|
|
81
|
+
- ❌ Solving different problem than assigned
|
|
82
|
+
- ❌ Cutting corners on quality
|
|
83
|
+
|
|
84
|
+
## REFLECTION DOCUMENTATION
|
|
85
|
+
|
|
86
|
+
After completing the reflection, document your analysis:
|
|
87
|
+
|
|
88
|
+
```markdown
|
|
89
|
+
## Pre-Completion Reflection
|
|
90
|
+
|
|
91
|
+
### Phase 1: Claim Verification
|
|
92
|
+
- **Claims**: [List what you're claiming works]
|
|
93
|
+
- **Evidence**: [List evidence for each claim]
|
|
94
|
+
- **Manual Testing**: [Describe manual validation performed]
|
|
95
|
+
- **Test Results**: [All tests passing? Include output]
|
|
96
|
+
|
|
97
|
+
### Phase 2: Risk Analysis
|
|
98
|
+
- **Potential Issues**: [What could go wrong?]
|
|
99
|
+
- **Untested Areas**: [What didn't you test?]
|
|
100
|
+
- **Error Analysis**: [Any errors in logs? Why are they OK?]
|
|
101
|
+
- **User Experience**: [What would user experience?]
|
|
102
|
+
|
|
103
|
+
### Phase 3: Validation Plan Check
|
|
104
|
+
- **Ship to Customers**: YES/NO [Would you ship this right now?]
|
|
105
|
+
- **Bet Money**: YES/NO [Would you bet money this works?]
|
|
106
|
+
- **Reproducible**: YES/NO [Can you reproduce success?]
|
|
107
|
+
- **Workflow Complete**: YES/NO [Followed all steps?]
|
|
108
|
+
|
|
109
|
+
### Phase 4: Self-Audit
|
|
110
|
+
- **Honesty Check**: YES/NO [Being completely honest?]
|
|
111
|
+
- **Evidence Quality**: YES/NO [Evidence complete and accurate?]
|
|
112
|
+
- **No Rushing**: YES/NO [Not rushing to completion?]
|
|
113
|
+
- **Correct Problem**: YES/NO [Solving the right problem?]
|
|
114
|
+
|
|
115
|
+
### Reflection Summary
|
|
116
|
+
[Brief summary of reflection analysis and any blockers identified]
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
**IMPORTANT**: After completing reflection, append your insights to the retrospective document:
|
|
120
|
+
- **File**: `retrospectives/issue-{issue-number}-{kebab-title}-postmortem.md`
|
|
121
|
+
- **If file exists**: Append new section with timestamp
|
|
122
|
+
- **If file doesn't exist**: Create it using the retrospective template
|
|
123
|
+
- **Section format**: `## Pre-Completion Reflection Insights ({date} - {current-phase})`
|
|
124
|
+
|
|
125
|
+
## ENFORCEMENT
|
|
126
|
+
|
|
127
|
+
### Mandatory Completion
|
|
128
|
+
- **REQUIRED**: All 4 phases must be completed before claiming work is done
|
|
129
|
+
- **MINIMUM TIME**: 10 minutes total reflection time
|
|
130
|
+
- **DOCUMENTATION**: Reflection analysis must be included in evidence
|
|
131
|
+
|
|
132
|
+
### Blocker Identification
|
|
133
|
+
If reflection identifies any blockers:
|
|
134
|
+
- **STOP**: Do not claim completion
|
|
135
|
+
- **FIX**: Address all identified issues
|
|
136
|
+
- **RE-REFLECT**: Complete reflection again after fixes
|
|
137
|
+
|
|
138
|
+
### Quality Gates
|
|
139
|
+
- ❌ **BLOCKER**: Any "NO" answers in Phase 3 or 4
|
|
140
|
+
- ❌ **BLOCKER**: Incomplete reflection documentation
|
|
141
|
+
- ❌ **BLOCKER**: Evidence doesn't support claims
|
|
142
|
+
- ❌ **BLOCKER**: Identified risks not addressed
|
|
143
|
+
|
|
144
|
+
## EXAMPLES
|
|
145
|
+
|
|
146
|
+
### Good Reflection Example
|
|
147
|
+
```markdown
|
|
148
|
+
### Phase 1: Claim Verification
|
|
149
|
+
- **Claims**: OAuth login flow works end-to-end
|
|
150
|
+
- **Evidence**: Screenshots of login → redirect → dashboard flow
|
|
151
|
+
- **Manual Testing**: Tested in Chrome, Firefox, Safari - all work
|
|
152
|
+
- **Test Results**: 15/15 tests passing, full output attached
|
|
153
|
+
|
|
154
|
+
### Phase 3: Validation Plan Check
|
|
155
|
+
- **Ship to Customers**: YES - Confident this works in production
|
|
156
|
+
- **Bet Money**: YES - Tested thoroughly, no concerns
|
|
157
|
+
- **Reproducible**: YES - Works consistently across browsers
|
|
158
|
+
- **Workflow Complete**: YES - Followed all implementation steps
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Bad Reflection Example
|
|
162
|
+
```markdown
|
|
163
|
+
### Phase 1: Claim Verification
|
|
164
|
+
- **Claims**: Login works
|
|
165
|
+
- **Evidence**: Tests pass
|
|
166
|
+
- **Manual Testing**: Didn't test manually, tests should be enough
|
|
167
|
+
- **Test Results**: 14/15 tests passing (93% is good enough)
|
|
168
|
+
|
|
169
|
+
### Phase 3: Validation Plan Check
|
|
170
|
+
- **Ship to Customers**: NO - Haven't tested manually
|
|
171
|
+
- **Bet Money**: NO - Not sure if it actually works
|
|
172
|
+
- **Reproducible**: UNKNOWN - Only ran tests once
|
|
173
|
+
- **Workflow Complete**: NO - Skipped manual validation
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## BENEFITS
|
|
177
|
+
|
|
178
|
+
1. **Prevents False Success**: Catches claims not backed by evidence
|
|
179
|
+
2. **Improves Quality**: Forces thorough validation before completion
|
|
180
|
+
3. **Builds Confidence**: Systematic validation increases confidence
|
|
181
|
+
4. **Reduces Rework**: Catches issues before they reach human review
|
|
182
|
+
5. **Develops Discipline**: Builds habit of thorough self-validation
|
|
183
|
+
|
|
184
|
+
## SUMMARY
|
|
185
|
+
|
|
186
|
+
The mandatory pre-completion reflection ensures agents:
|
|
187
|
+
- Validate every claim with concrete evidence
|
|
188
|
+
- Think from user perspective about potential issues
|
|
189
|
+
- Perform comprehensive testing before claiming completion
|
|
190
|
+
- Maintain integrity and honesty in status reporting
|
|
191
|
+
- Deliver production-ready work that actually solves the problem
|
|
192
|
+
|
|
193
|
+
**Remember**: 10 minutes of reflection can save hours of rework.
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# Merge Requirements
|
|
2
|
+
|
|
3
|
+
## INTENT
|
|
4
|
+
To ensure the stability of the `master` branch and prevent accidental overwrites by requiring all agents to apply their local changes *on top of* the latest `master` branch changes, ensuring `master`'s history is never overwritten.
|
|
5
|
+
|
|
6
|
+
## PRINCIPLES
|
|
7
|
+
- **Rebase, Don't Merge:** Always rebase your feature branch on top of the latest `master` to maintain a clean, linear history and ensure changes from `master` are applied first.
|
|
8
|
+
- **Verify After Rebase:** Run all tests and builds *after* a successful rebase to ensure stability before pushing.
|
|
9
|
+
- **Document Conflict Resolution:** Clearly document how any rebase conflicts were resolved, emphasizing how `master`'s changes were preserved.
|
|
10
|
+
- **Force-with-Lease:** When pushing a rebased branch, use `git push --force-with-lease` to avoid overwriting work from other contributors.
|
|
11
|
+
|
|
12
|
+
## WORKFLOW
|
|
13
|
+
|
|
14
|
+
## MANDATORY PRE-PUSH WORKFLOW
|
|
15
|
+
|
|
16
|
+
### Before ANY push to your feature branch:
|
|
17
|
+
```bash
|
|
18
|
+
# 1. Sync with latest master
|
|
19
|
+
git fetch origin
|
|
20
|
+
git rebase origin/master
|
|
21
|
+
|
|
22
|
+
# 2. If conflicts occur, resolve them using conflict resolution guide
|
|
23
|
+
# (Git will pause and show you conflict markers)
|
|
24
|
+
git rebase --continue
|
|
25
|
+
|
|
26
|
+
# 3. Verify everything works
|
|
27
|
+
# Use project-specific smoke test command from .fraim/config.json if available
|
|
28
|
+
# Check: cat .fraim/config.json | grep "smokeTestCommand"
|
|
29
|
+
# Use configured command or default to:
|
|
30
|
+
npm run build
|
|
31
|
+
|
|
32
|
+
npm run test-smoke test*.ts
|
|
33
|
+
|
|
34
|
+
# 4. Only then push
|
|
35
|
+
git push origin <your-feature-branch> --force-with-lease
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### This workflow is MANDATORY because:
|
|
39
|
+
- Prevents creating stale PRs
|
|
40
|
+
- Ensures your changes work with latest master
|
|
41
|
+
- Reduces merge conflicts
|
|
42
|
+
- Required by GitHub branch protection rules
|
|
43
|
+
|
|
44
|
+
## DETAILED REBASE PROCESS
|
|
45
|
+
1. **Sync with `master`:** Before pushing your changes, rebase your feature branch on top of the latest `master` branch. This applies `master`'s changes first, then your local changes on top.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
git checkout <your-feature-branch>
|
|
49
|
+
git fetch origin
|
|
50
|
+
git rebase origin/master
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
2. **Resolve Rebase Conflicts:** If there are any conflicts during the rebase, you must resolve them intelligently. The rebase process will pause to allow you to fix the files. Your goal is to preserve the changes from `master` while reapplying your feature's changes.
|
|
54
|
+
|
|
55
|
+
## CONFLICT RESOLUTION DURING REBASE
|
|
56
|
+
|
|
57
|
+
### When Git Pauses for Conflicts:
|
|
58
|
+
1. **Read the conflict markers carefully:**
|
|
59
|
+
- `<<<<<<< HEAD` = Your changes
|
|
60
|
+
- `=======` = Separator
|
|
61
|
+
- `>>>>>>> origin/master` = Master's changes
|
|
62
|
+
|
|
63
|
+
2. **Understand what each version does:**
|
|
64
|
+
- Master's version = What's already in production
|
|
65
|
+
- Your version = What you're trying to add
|
|
66
|
+
|
|
67
|
+
3. **Resolution Strategy:**
|
|
68
|
+
- **Keep master's base** (it's already tested/deployed)
|
|
69
|
+
- **Add your enhancements** on top
|
|
70
|
+
- **Never overwrite master's working code**
|
|
71
|
+
- **Never lose your new functionality**
|
|
72
|
+
|
|
73
|
+
4. **Common Conflict Scenarios:**
|
|
74
|
+
|
|
75
|
+
**Scenario 1: Same function, different implementations**
|
|
76
|
+
```typescript
|
|
77
|
+
<<<<<<< HEAD (your changes)
|
|
78
|
+
async function processMessage(message: string) {
|
|
79
|
+
// Your new implementation
|
|
80
|
+
return await this.messageService.process(message);
|
|
81
|
+
}
|
|
82
|
+
=======
|
|
83
|
+
async function processMessage(message: string) {
|
|
84
|
+
// Master's updated implementation
|
|
85
|
+
return await this.messageService.processWithValidation(message);
|
|
86
|
+
}
|
|
87
|
+
>>>>>>> origin/master
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Resolution:** Keep master's version + add your enhancements
|
|
91
|
+
```typescript
|
|
92
|
+
async function processMessage(message: string) {
|
|
93
|
+
// Master's base implementation
|
|
94
|
+
const result = await this.messageService.processWithValidation(message);
|
|
95
|
+
// Your additional logic
|
|
96
|
+
return await this.enhanceResult(result);
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Scenario 2: Different functions, no overlap**
|
|
101
|
+
```typescript
|
|
102
|
+
<<<<<<< HEAD (your changes)
|
|
103
|
+
// Your new function
|
|
104
|
+
async function newFeature() {
|
|
105
|
+
return "new stuff";
|
|
106
|
+
}
|
|
107
|
+
=======
|
|
108
|
+
// Master's new function
|
|
109
|
+
async function masterFeature() {
|
|
110
|
+
return "master stuff";
|
|
111
|
+
}
|
|
112
|
+
>>>>>>> origin/master
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Resolution:** Keep both (no conflict, just different functions)
|
|
116
|
+
```typescript
|
|
117
|
+
// Master's function
|
|
118
|
+
async function masterFeature() {
|
|
119
|
+
return "master stuff";
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
// Your function
|
|
123
|
+
async function newFeature() {
|
|
124
|
+
return "new stuff";
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
5. **After resolving conflicts:**
|
|
129
|
+
```bash
|
|
130
|
+
# After resolving conflicts in your IDE
|
|
131
|
+
git add <resolved-file-1> <resolved-file-2>
|
|
132
|
+
git rebase --continue
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### NEVER DO THIS:
|
|
136
|
+
❌ "Accept Current Change" (your version) - overwrites master
|
|
137
|
+
❌ "Accept Incoming Change" (master's version) - loses your work
|
|
138
|
+
❌ "Accept Both Changes" - creates duplicate code
|
|
139
|
+
|
|
140
|
+
### ALWAYS DO THIS:
|
|
141
|
+
✅ Read both versions carefully
|
|
142
|
+
✅ Understand what each change does
|
|
143
|
+
✅ Merge intelligently or choose the better implementation
|
|
144
|
+
✅ Test the resolution with: npm run build && [use smokeTestCommand from .fraim/config.json or default smoke test]
|
|
145
|
+
✅ Document your resolution in the PR description
|
|
146
|
+
|
|
147
|
+
3. **Run Verification Checks:** After the rebase is complete, you must run all local verification checks to ensure the codebase is stable.
|
|
148
|
+
* **Build the project:** Run the build command to ensure there are no compilation errors.
|
|
149
|
+
* **Run tests:** Execute the full test suite to confirm that your changes have not introduced any regressions.
|
|
150
|
+
|
|
151
|
+
4. **Push Your Changes:** Once all checks have passed, push your rebased branch. You must use `--force-with-lease` because the rebase has rewritten your branch's commit history.
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
git push origin <your-feature-branch> --force-with-lease
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
5. **Pull Request:** When creating a pull request, the description must include a confirmation that this rebase process was followed and a detailed summary of how any conflicts were resolved.
|
|
158
|
+
|
|
159
|
+
## PR Description Template
|
|
160
|
+
```markdown
|
|
161
|
+
## Merge Process Confirmation
|
|
162
|
+
- [ ] Rebased on latest master
|
|
163
|
+
- [ ] Resolved X conflicts in files: [list files]
|
|
164
|
+
- [ ] Resolution strategy: [explain what you did]
|
|
165
|
+
- [ ] Verified with: npm run build && [used smokeTestCommand from .fraim/config.json]
|
|
166
|
+
- [ ] All tests passing: ✅
|
|
167
|
+
|
|
168
|
+
## Conflict Resolution Summary
|
|
169
|
+
### Files with conflicts:
|
|
170
|
+
- `src/file1.ts`: [Brief description of how conflict was resolved]
|
|
171
|
+
- `src/file2.ts`: [Brief description of how conflict was resolved]
|
|
172
|
+
|
|
173
|
+
### Resolution approach:
|
|
174
|
+
[Explain your overall strategy - e.g., "Kept master's base implementation and added my enhancements on top"]
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## FINAL MERGE PROCESS (After PR Approval)
|
|
178
|
+
|
|
179
|
+
### 6. **Execute the Merge:** Once your PR is approved and ready, perform the final merge:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
# 1. Navigate to your PR on GitHub
|
|
183
|
+
# 2. Click "Merge pull request" button
|
|
184
|
+
# 3. GitHub will automatically:
|
|
185
|
+
# - Rebase your branch on latest master
|
|
186
|
+
# - Apply your changes on top
|
|
187
|
+
# - Create a clean, linear history
|
|
188
|
+
# - Merge into master
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### 7. **Post-Merge Cleanup:** After successful merge:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
# 1. Switch to master and pull latest changes
|
|
195
|
+
git checkout master
|
|
196
|
+
git pull origin master
|
|
197
|
+
|
|
198
|
+
# 2. Delete your feature branch (local)
|
|
199
|
+
git branch -d <your-feature-branch>
|
|
200
|
+
|
|
201
|
+
# 3. Delete your feature branch (remote)
|
|
202
|
+
git push origin --delete <your-feature-branch>
|
|
203
|
+
|
|
204
|
+
# 4. Verify the merge was successful
|
|
205
|
+
git log --oneline -5
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### 8. **Final Verification:** Ensure everything is working:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
# Run final tests to confirm merge didn't break anything
|
|
212
|
+
npm run build
|
|
213
|
+
# Use project-specific smoke test command from .fraim/config.json if available
|
|
214
|
+
# Check: cat .fraim/config.json | grep "smokeTestCommand"
|
|
215
|
+
# Use configured command or default to:
|
|
216
|
+
npm run test-smoke test*.ts
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
## MERGE WORKFLOW SUMMARY
|
|
220
|
+
|
|
221
|
+
### Complete Process:
|
|
222
|
+
1. **Development** → Work on feature branch
|
|
223
|
+
2. **Pre-Push** → Rebase on master, resolve conflicts, test
|
|
224
|
+
3. **Push** → Push to GitHub
|
|
225
|
+
4. **PR Creation** → Create PR with detailed description
|
|
226
|
+
5. **Review** → Wait for approval
|
|
227
|
+
6. **Merge** → Click "Merge pull request" on GitHub
|
|
228
|
+
7. **Cleanup** → Delete branches, verify merge
|
|
229
|
+
8. **Verification** → Run final tests
|
|
230
|
+
|
|
231
|
+
### Key Points:
|
|
232
|
+
- ✅ **GitHub handles the final rebase** automatically during merge
|
|
233
|
+
- ✅ **No manual rebasing** needed before merge
|
|
234
|
+
- ✅ **Linear history** maintained automatically
|
|
235
|
+
- ✅ **All conflicts resolved** during the merge process
|
|
236
|
+
- ✅ **Clean, up-to-date master** branch
|
|
237
|
+
|
|
238
|
+
By following this process, we ensure that the `master` branch always remains in a stable and deployable state. Failure to follow these rules will result in the rejection of your pull request.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Rule: simplicity
|
|
2
|
+
|
|
3
|
+
**Path:** `rules/simplicity.md`
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Simplicity
|
|
8
|
+
|
|
9
|
+
## INTENT
|
|
10
|
+
To maintain code quality and development velocity by preventing over-engineering, ensuring agents focus on solving the specific problem at hand rather than building unnecessary complexity.
|
|
11
|
+
|
|
12
|
+
## PRINCIPLES
|
|
13
|
+
- Keep it simple. Don't over-engineer.
|
|
14
|
+
- Don't over-think it.
|
|
15
|
+
- Focus on the assigned issue only.
|
|
16
|
+
- Don't fix other issues or make unrelated changes.
|
|
17
|
+
|
|
18
|
+
## REQUIREMENTS
|
|
19
|
+
- While fixing an issue, focus on that issue only
|
|
20
|
+
- Don't fix other issues or make unrelated changes
|
|
21
|
+
- If you find other issues that must be fixed, include them in your final report as a suggested Git issue
|
|
22
|
+
- Don't over-engineer solutions
|
|
23
|
+
- Choose the simplest approach that solves the problem
|
|
24
|
+
- **NEVER use placeholder comments** like "For now", "TODO", "FIXME", or "This is a placeholder"
|
|
25
|
+
- **ALWAYS implement complete solutions** - if something needs to be customized later, implement it properly with clear configuration
|
|
26
|
+
|
|
27
|
+
## PROTOTYPE-FIRST DEVELOPMENT PATTERN
|
|
28
|
+
|
|
29
|
+
### Core Principle
|
|
30
|
+
**Always prototype the end-to-end solution manually before engineering it correctly.**
|
|
31
|
+
|
|
32
|
+
### Development Flow
|
|
33
|
+
1. **Prototype**: Build simplest possible solution that works end-to-end
|
|
34
|
+
2. **Manual Validation**: Test each step manually using browser/API calls
|
|
35
|
+
3. **Verify**: Confirm everything works before creating automated tests
|
|
36
|
+
4. **Engineer**: Refactor to production quality once proven to work
|
|
37
|
+
5. **Automate**: Create Playwright tests only after manual validation
|
|
38
|
+
|
|
39
|
+
### Anti-Patterns to Avoid
|
|
40
|
+
- ❌ **"Assume It Works"**: Creating tests before manual validation
|
|
41
|
+
- ❌ **"Over-Engineer First"**: Building complex architecture before proving simple solution works
|
|
42
|
+
- ❌ **"Test-Driven Over-Engineering"**: Writing comprehensive test suites for unproven solutions
|
|
43
|
+
- ❌ **"Band-Aid Fixes"**: Adding delays, retries, workarounds instead of fixing root cause
|
|
44
|
+
- ❌ **"Resource Waste"**: Running expensive operations repeatedly without analyzing failures
|
|
45
|
+
|
|
46
|
+
### Validation Requirements
|
|
47
|
+
- **Manual Testing**: Use browser/curl to test each step manually
|
|
48
|
+
- **End-to-End Flow**: Verify complete user journey works
|
|
49
|
+
- **No Assumptions**: Don't assume anything works until manually verified
|
|
50
|
+
- **Simple First**: Start with simplest possible implementation
|
|
51
|
+
- **Prove Then Improve**: Only add complexity after proving simple version works
|
|
52
|
+
|
|
53
|
+
## RESOURCE WASTE PREVENTION
|
|
54
|
+
- Maximum 2 retries for expensive operations (Playwright, API calls, database)
|
|
55
|
+
- After 2 failures: STOP, analyze, propose different approach
|
|
56
|
+
- **STOP** if tests are consuming significant resources repeatedly
|
|
57
|
+
- **Manual validation required** before creating automated tests
|
|
58
|
+
|
|
59
|
+
## EXAMPLES
|
|
60
|
+
|
|
61
|
+
### Good: Prototype-First Development
|
|
62
|
+
```
|
|
63
|
+
Issue: "Add OAuth login"
|
|
64
|
+
Action:
|
|
65
|
+
1. Built simple OAuth callback → JWT → redirect
|
|
66
|
+
2. Manually tested with browser (login → redirect → dashboard works)
|
|
67
|
+
3. Verified end-to-end flow works
|
|
68
|
+
4. Then created Playwright tests
|
|
69
|
+
Result: Working solution, no overengineering
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Bad: Over-Engineering First
|
|
73
|
+
```
|
|
74
|
+
Issue: "Add OAuth login"
|
|
75
|
+
Action:
|
|
76
|
+
1. Built complex session management system
|
|
77
|
+
2. Created comprehensive test suite
|
|
78
|
+
3. Added session validation endpoints
|
|
79
|
+
4. Created infinite redirect loops
|
|
80
|
+
5. Added delays/retries to fix timing issues
|
|
81
|
+
Result: Over-engineered, resource waste, doesn't work
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Good: Manual Validation First
|
|
85
|
+
```
|
|
86
|
+
Issue: "Fix API endpoint"
|
|
87
|
+
Action:
|
|
88
|
+
1. Fixed the code
|
|
89
|
+
2. Tested with curl to verify it works
|
|
90
|
+
3. Tested in browser to verify UI works
|
|
91
|
+
4. Then created automated tests
|
|
92
|
+
Result: Confident solution works before automation
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Bad: Assume It Works
|
|
96
|
+
```
|
|
97
|
+
Issue: "Fix API endpoint"
|
|
98
|
+
Action:
|
|
99
|
+
1. Fixed the code
|
|
100
|
+
2. Created Playwright tests immediately
|
|
101
|
+
3. Tests fail because solution doesn't actually work
|
|
102
|
+
4. Keep retrying tests instead of fixing code
|
|
103
|
+
Result: Wasted resources, false confidence
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Good: Simple Solution
|
|
107
|
+
```
|
|
108
|
+
Issue: "Add error message for invalid input"
|
|
109
|
+
Action: Added single validation check with clear error message
|
|
110
|
+
Result: Clean, focused solution
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Bad: Complex Solution
|
|
114
|
+
```
|
|
115
|
+
Issue: "Add error message for invalid input"
|
|
116
|
+
Action: Built comprehensive validation framework with multiple error types, internationalization, and complex state management
|
|
117
|
+
Result: Over-engineered for simple requirement
|
|
118
|
+
```
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Software Development Lifecycle
|
|
2
|
+
|
|
3
|
+
## INTENT
|
|
4
|
+
To provide a structured, phase-based approach to issue resolution that ensures proper planning, implementation, testing, and cleanup while maintaining coordination with other agents and respecting project governance.
|
|
5
|
+
|
|
6
|
+
## PRINCIPLES
|
|
7
|
+
- **Phase-Based Development**: Clear phases with specific deliverables
|
|
8
|
+
- **Branch Safety**: Never work on master, always use feature branches
|
|
9
|
+
- **Local Development**: Work in isolated clones to prevent conflicts
|
|
10
|
+
- **Coordination**: Use GitHub for agent coordination and status management
|
|
11
|
+
- **Governance**: Respect CODEOWNERS and project policies
|
|
12
|
+
|
|
13
|
+
## CORE WORKFLOW
|
|
14
|
+
Always work on the feature branch for the current issue: `feature/<issue#>-<kebab-title>`. Never push to master.
|
|
15
|
+
|
|
16
|
+
### Development Workflow
|
|
17
|
+
1. **Clone Setup**: Work in your own cloned repository folder. Folder name should be `Ashley Calendar AI - Issue {issue_number}`
|
|
18
|
+
2. **Branch Management**: Create/checkout feature branch for your issue
|
|
19
|
+
3. **Local Development**: Make changes, run tests locally
|
|
20
|
+
4. **Check before commit**: Only commit after approval from the user.
|
|
21
|
+
5. **Remote Coordination**: Use GitHub MCP for issue labels
|
|
22
|
+
|
|
23
|
+
## MANDATORY PRE-COMMIT VALIDATION
|
|
24
|
+
Before ANY commit, run: `git branch` and verify NOT on master
|
|
25
|
+
|
|
26
|
+
## PHASES
|
|
27
|
+
|
|
28
|
+
### Design Phase
|
|
29
|
+
- **Trigger**: Set ISSUE to `phase:design`
|
|
30
|
+
- **Deliverable**: Create RFC document
|
|
31
|
+
- **Status**: Automatically set to `status:wip`
|
|
32
|
+
|
|
33
|
+
### Implementation Phase
|
|
34
|
+
- **Trigger**: Set ISSUE to `phase:impl`
|
|
35
|
+
- **Deliverable**: Working code with tests
|
|
36
|
+
- **Status**: Set to `status:needs-review` when ready
|
|
37
|
+
|
|
38
|
+
## STATUS MANAGEMENT
|
|
39
|
+
- **WIP**: Automatically set when entering new phase
|
|
40
|
+
- **Needs Review**: Set this when work is ready for review
|
|
41
|
+
- **Complete**: Automatically set when PR is approved
|
|
42
|
+
|
|
43
|
+
## EXAMPLES
|
|
44
|
+
|
|
45
|
+
### Good: Proper Phase Management
|
|
46
|
+
```
|
|
47
|
+
Issue #84: "Fix calendar sync timeout"
|
|
48
|
+
1. Set phase:design → Create RFC for retry logic
|
|
49
|
+
2. Set phase:impl → Implement exponential backoff
|
|
50
|
+
3. Set status:needs-review → Ready for code review
|
|
51
|
+
4. PR approved → Set status:complete
|
|
52
|
+
Result: Clear progression through phases
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Bad: Skipping Phases
|
|
56
|
+
```
|
|
57
|
+
Issue #84: "Fix calendar sync timeout"
|
|
58
|
+
1. Jump straight to coding without design
|
|
59
|
+
2. No RFC created
|
|
60
|
+
3. Implementation lacks proper planning
|
|
61
|
+
Result: Incomplete solution, potential rework
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## PRE-PHASE VALIDATION
|
|
65
|
+
|
|
66
|
+
### Before Starting Any Phase
|
|
67
|
+
Agents MUST complete validation checklist:
|
|
68
|
+
|
|
69
|
+
1. **Read Relevant Rules**:
|
|
70
|
+
- [ ] Read `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
|
|
71
|
+
- [ ] Read phase-specific workflow via `get_fraim_file` (e.g. `workflows/product-building/design.md`)
|
|
72
|
+
- [ ] Read retrospectives folder thoroughly and understand past learnings
|
|
73
|
+
|
|
74
|
+
2. **Verify Environment**:
|
|
75
|
+
- [ ] Confirm working directory is correct
|
|
76
|
+
- [ ] Verify branch exists and is checked out
|
|
77
|
+
- [ ] Check issue labels are correct
|
|
78
|
+
|
|
79
|
+
3. **Template Validation**:
|
|
80
|
+
- [ ] Locate correct template file
|
|
81
|
+
- [ ] Verify template exists and is readable
|
|
82
|
+
- [ ] Confirm naming convention understanding
|
|
83
|
+
|
|
84
|
+
4. **Technical Understanding**:
|
|
85
|
+
- [ ] Understand relevant technical patterns for the issue
|
|
86
|
+
- [ ] Plan test strategy for core functionality
|
|
87
|
+
|
|
88
|
+
### Validation Failure Response
|
|
89
|
+
If any validation step fails:
|
|
90
|
+
1. Stop work immediately
|
|
91
|
+
2. Read missing documentation
|
|
92
|
+
3. Ask clarifying questions if needed
|
|
93
|
+
4. Resume only after validation complete
|
|
94
|
+
|
|
95
|
+
## CLEANUP
|
|
96
|
+
When user confirms code is correctly merged into master, confirm with the user, then
|
|
97
|
+
- delete remote branch
|
|
98
|
+
- delete local branch
|
|
99
|
+
- remove your local clone folder:
|
|
100
|
+
```
|
|
101
|
+
cd ..
|
|
102
|
+
Remove-Item -Recurse -Force "Ashley Calendar AI - Issue {issue_number}"
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Respect CODEOWNERS; don't modify auth/CI without approval.
|