From e8af39aed6af1a5b1ed3d3c193cb209a2efe338e Mon Sep 17 00:00:00 2001 From: Reza Rezvani Date: Wed, 5 Nov 2025 11:37:53 +0100 Subject: [PATCH] feat(foundation): create directory structure and standards library - Create root-level directories: agents/, commands/, standards/, templates/ - Port 5 core standards from global Claude standards - Adapt standards for claude-skills context (cs-* prefix, Python tools, skills) - Create sprint planning documents (context.md, plan.md) - All directories tracked with .gitkeep files Standards created: - communication-standards.md (absolute honesty, zero fluff, pragmatic focus) - quality-standards.md (Python tool quality, agent workflows, testing) - git-workflow-standards.md (conventional commits, semantic versioning) - documentation-standards.md (Markdown standards, living docs, templates) - security-standards.md (secret detection, dependency security, input validation) Sprint plan ready for Days 1-6 implementation. Phase: 1 (Foundation) Issues: #8, #9 --- agents/c-level/.gitkeep | 0 agents/marketing/.gitkeep | 0 agents/product/.gitkeep | 0 commands/.gitkeep | 0 .../delivery/sprint-11-05-2025/context.md | 238 +++++ .../delivery/sprint-11-05-2025/plan.md | 866 ++++++++++++++++++ standards/communication/.gitkeep | 0 .../communication/communication-standards.md | 38 + standards/documentation/.gitkeep | 0 .../documentation/documentation-standards.md | 545 +++++++++++ standards/git/.gitkeep | 0 standards/git/git-workflow-standards.md | 439 +++++++++ standards/quality/.gitkeep | 0 standards/quality/quality-standards.md | 319 +++++++ standards/security/.gitkeep | 0 standards/security/security-standards.md | 503 ++++++++++ templates/.gitkeep | 0 17 files changed, 2948 insertions(+) create mode 100644 agents/c-level/.gitkeep create mode 100644 agents/marketing/.gitkeep create mode 100644 agents/product/.gitkeep create mode 100644 commands/.gitkeep create mode 100644 documentation/delivery/sprint-11-05-2025/context.md create mode 100644 documentation/delivery/sprint-11-05-2025/plan.md create mode 100644 standards/communication/.gitkeep create mode 100644 standards/communication/communication-standards.md create mode 100644 standards/documentation/.gitkeep create mode 100644 standards/documentation/documentation-standards.md create mode 100644 standards/git/.gitkeep create mode 100644 standards/git/git-workflow-standards.md create mode 100644 standards/quality/.gitkeep create mode 100644 standards/quality/quality-standards.md create mode 100644 standards/security/.gitkeep create mode 100644 standards/security/security-standards.md create mode 100644 templates/.gitkeep diff --git a/agents/c-level/.gitkeep b/agents/c-level/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agents/marketing/.gitkeep b/agents/marketing/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agents/product/.gitkeep b/agents/product/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/commands/.gitkeep b/commands/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/documentation/delivery/sprint-11-05-2025/context.md b/documentation/delivery/sprint-11-05-2025/context.md new file mode 100644 index 0000000..7747ccf --- /dev/null +++ b/documentation/delivery/sprint-11-05-2025/context.md @@ -0,0 +1,238 @@ +# Sprint Context: Skill-Agent Integration Phase 1-2 + +**Sprint ID:** sprint-11-05-2025 +**Sprint Name:** Skill-Agent Integration Foundation +**Start Date:** November 5, 2025 +**Target End Date:** November 19, 2025 +**Duration:** 14 days (2 weeks) +**Sprint Type:** Foundation Build + +--- + +## Sprint Goal + +**Primary Goal:** +Build the foundational agent integration system for claude-code-skills, enabling users to invoke specialized cs-* agents that seamlessly integrate with the existing 42 production skills. + +**Success Criteria:** +- ✅ Root-level directory structure created (agents/, commands/, standards/, templates/) +- ✅ 5 core standards ported from factory and adapted +- ✅ 5 agents fully implemented (cs-content-creator, cs-demand-gen-specialist, cs-ceo-advisor, cs-cto-advisor, cs-product-manager) +- ✅ Agent template and creation guide complete +- ✅ All relative paths resolve correctly +- ✅ Python tools execute successfully from agent context +- ✅ Documentation updated (README, INSTALL, USAGE, CLAUDE) +- ✅ All quality gates pass + +--- + +## Context & Background + +### Why This Sprint? + +The claude-code-skills repository currently contains 42 production-ready skills across 6 domains (marketing, C-level advisory, product team, project management, engineering, RA/QM). Each skill includes Python automation tools, knowledge bases, and templates. + +**Current Gap:** +- Skills exist as standalone packages +- No orchestration layer for workflows +- Users must manually invoke Python scripts +- No guided workflows or best practices + +**Solution:** +Agent integration provides a workflow orchestration layer where specialized agents (cs-* prefix) invoke skills, coordinate Python tools, and guide users through complex multi-step processes. + +### Strategic Value + +1. **User Experience:** Transform from "tool collection" to "guided workflows" +2. **Marketplace Ready:** Foundation for Anthropic plugin marketplace distribution +3. **Scalability:** Template system enables rapid expansion to 42+ agents +4. **Differentiation:** Only skill library with built-in agent orchestration + +--- + +## Scope + +### In Scope (Phase 1-2) + +**Phase 1: Core Structure (Days 1)** +- Root-level directory creation +- Standards library (5 files) + +**Phase 2: Agent Implementation (Days 2-4)** +- Marketing agents (2) +- C-level agents (2) +- Product agent (1) +- Agent template & creation guide + +**Phase 4-5: Documentation & Testing (Days 5-6)** +- Documentation updates (README, INSTALL, USAGE, CLAUDE) +- Comprehensive testing & validation + +### Out of Scope (Future Phases) + +- Installation script (install.sh) → Phase 3 +- Uninstall script (uninstall.sh) → Phase 3 +- Remaining 37 agents (project management, engineering, RA/QM) → Future sprints +- Plugin marketplace submission → Phase 6-7 +- Backwards compatibility migration → Phase 3 + +--- + +## Key Stakeholders + +**Primary:** +- Repository users (developers, product teams, marketers, executives) +- Future Anthropic marketplace users + +**Secondary:** +- Contributors to claude-code-skills +- Teams using skills in production + +--- + +## Dependencies + +### External Dependencies + +1. **GitHub Automation** ✅ (Complete) + - Smart-sync workflow configured + - PROJECTS_TOKEN secret added + - Project #9 board configured + - Labels created + +2. **Existing Skills** ✅ (Complete) + - 42 production skills + - 97 Python automation tools + - Complete knowledge bases + +### Internal Dependencies + +1. **Implementation Plan** ✅ (Complete) + - `documentation/implementation/implementation-plan-november-2025.md` + - 50+ pages with detailed specifications + +2. **GitHub Issues** ✅ (Complete) + - 8 issues created (#8-#16, excluding #10) + - All linked to Milestone: Skill-Agent Integration v1.0 + - All on Project #9 board + +3. **Factory Reference** ✅ (Available) + - claude-code-skills-factory project + - Standards files to port + - Agent patterns to reference + +--- + +## Risks & Mitigation + +### Risk 1: Relative Path Resolution Failures +**Probability:** Medium +**Impact:** High +**Mitigation:** +- Test paths early and often +- Create validation script for path testing +- Document path patterns in creation guide +**Fallback:** Use absolute paths with environment variables + +### Risk 2: Python Tool Execution Issues +**Probability:** Low +**Impact:** Medium +**Mitigation:** +- Test each tool from agent context +- Verify working directory assumptions +- Document execution requirements +**Fallback:** Provide wrapper scripts + +### Risk 3: Scope Creep (Trying to do all 42 agents) +**Probability:** High +**Impact:** High +**Mitigation:** +- Strict focus on 5 foundational agents +- Template system enables future expansion +- Document "out of scope" clearly +**Fallback:** Defer additional agents to future sprints + +### Risk 4: Documentation Burden +**Probability:** Medium +**Impact:** Medium +**Mitigation:** +- Use agent template to standardize +- Reference existing skill documentation +- Keep agent docs focused on workflows +**Fallback:** Minimal viable documentation for v1.0 + +--- + +## Success Metrics + +### Quantitative Metrics + +- **Directory Structure:** 10 directories created +- **Standards Files:** 5 files ported and adapted +- **Agents Created:** 5 agents fully implemented +- **Documentation Files:** 4 files updated/created +- **Test Coverage:** 100% of agents tested +- **Path Resolution:** 100% success rate +- **Python Tool Execution:** 100% success rate + +### Qualitative Metrics + +- **User Experience:** Clear, guided workflows in each agent +- **Code Quality:** All quality gates pass +- **Documentation Quality:** Beginner-friendly, actionable +- **Maintainability:** Template enables easy agent creation +- **Architecture:** Clean separation of skills vs agents + +--- + +## Sprint Team + +**Lead:** Implementation Team +**Contributors:** +- Documentation Team +- Quality Assurance Team + +**Reviewers:** +- Repository Maintainer +- Domain Experts (marketing, C-level, product) + +--- + +## Related Documents + +- **Implementation Plan:** `documentation/implementation/implementation-plan-november-2025.md` +- **GitHub Milestone:** [Skill-Agent Integration v1.0](https://github.com/alirezarezvani/claude-skills/milestone/1) +- **Project Board:** [Project #9: @claude-code-skills](https://github.com/users/alirezarezvani/projects/9) +- **GitHub Issues:** #8, #9, #11, #12, #13, #14, #15, #16 +- **Factory Reference:** `/Users/rezarezvani/projects/claude-code-skills-factory` + +--- + +## Sprint Schedule Overview + +**Week 1 (Nov 5-8):** +- Days 1: Foundation (directories, standards) +- Days 2-4: Agents (marketing, C-level, product) + +**Week 2 (Nov 11-15):** +- Days 5-6: Documentation & testing +- Buffer: 3 days for unexpected issues + +**Target Completion:** November 15, 2025 (4 days buffer before Nov 19 deadline) + +--- + +## Next Steps + +1. ✅ Review sprint plan (context.md + plan.md) +2. ✅ Confirm sprint goals and scope +3. ✅ Begin implementation in optimal order +4. Track progress daily on Project #9 board +5. Update living docs (README, CLAUDE) as we complete phases + +--- + +**Document Version:** 1.0 +**Created:** November 5, 2025 +**Last Updated:** November 5, 2025 +**Status:** Active Sprint diff --git a/documentation/delivery/sprint-11-05-2025/plan.md b/documentation/delivery/sprint-11-05-2025/plan.md new file mode 100644 index 0000000..57bb58b --- /dev/null +++ b/documentation/delivery/sprint-11-05-2025/plan.md @@ -0,0 +1,866 @@ +# Sprint Plan: Skill-Agent Integration Phase 1-2 + +**Sprint:** sprint-11-05-2025 +**Duration:** 14 days (Nov 5 - Nov 19, 2025) +**Target Completion:** Day 6 (Nov 15, 2025) with 4-day buffer + +--- + +## Sprint Execution Strategy + +### Critical Path (Must Complete in Sequence) + +``` +Day 1: Foundation + ↓ +Days 2-4: Parallel Agent Development + ↓ +Days 5-6: Documentation & Testing +``` + +### Work Distribution + +- **Sequential Work:** Days 1 (foundation must complete first) +- **Parallel Work:** Days 2-4 (agents can be built concurrently once foundation exists) +- **Final Integration:** Days 5-6 (documentation and testing) + +--- + +## Day 1: Foundation Build (November 5, 2025) + +**Goal:** Complete Phase 1 - Establish directory structure and standards library + +**Status:** 🎯 START HERE + +### Morning Session (3 hours) + +#### Task 1.1: Create Root Directory Structure +**GitHub Issue:** [#8 - Create root-level directory structure](https://github.com/alirezarezvani/claude-skills/issues/8) +**Estimated Time:** 30 minutes +**Priority:** P1 - CRITICAL (blocks all other work) + +**Steps:** +```bash +# 1. Create agent directories +mkdir -p agents/marketing +mkdir -p agents/c-level +mkdir -p agents/product + +# 2. Create commands directory +mkdir -p commands + +# 3. Create standards directories +mkdir -p standards/communication +mkdir -p standards/quality +mkdir -p standards/git +mkdir -p standards/documentation +mkdir -p standards/security + +# 4. Create templates directory +mkdir -p templates + +# 5. Verify structure +tree agents commands standards templates + +# 6. Update .gitignore if needed +# (ensure these directories are tracked, not ignored) +``` + +**Acceptance Criteria:** +- [ ] All 10 directories created +- [ ] No conflicts with existing structure +- [ ] Directories tracked by git +- [ ] Structure matches implementation plan + +**Deliverable:** Directory structure ready for content + +--- + +#### Task 1.2: Port Core Standards from Factory +**GitHub Issue:** [#9 - Port core standards from factory](https://github.com/alirezarezvani/claude-skills/issues/9) +**Estimated Time:** 2.5 hours +**Priority:** P1 - HIGH +**Depends On:** Task 1.1 (directories must exist) + +**Standards to Port:** + +1. **communication-standards.md** (30 min) + ```bash + # Source: ~/projects/claude-code-skills-factory/.claude/standards/communication/ + # Target: standards/communication/communication-standards.md + ``` + - Replace factory-specific references → claude-skills context + - Replace rr-* agents → cs-* agents + - Update file paths to root-level structure + - Validate: No broken links, markdown passes linting + +2. **quality-standards.md** (30 min) + ```bash + # Source: factory/.claude/standards/quality/ + # Target: standards/quality/quality-standards.md + ``` + - Code quality requirements + - Testing standards (focus on Python tool testing) + - Review checklist + +3. **git-workflow-standards.md** (30 min) + ```bash + # Source: factory/.claude/standards/git/ + # Target: standards/git/git-workflow-standards.md + ``` + - Conventional commits + - Branch naming + - PR requirements + - Commit message templates + +4. **documentation-standards.md** (30 min) + ```bash + # Source: factory/.claude/standards/documentation/ + # Target: standards/documentation/documentation-standards.md + ``` + - Markdown formatting + - File naming conventions + - Structure requirements + - Living documentation principles + +5. **security-standards.md** (30 min) + ```bash + # Source: factory/.claude/standards/security/ + # Target: standards/security/security-standards.md + ``` + - Secret detection + - Dependency scanning + - Security checklist + - Vulnerability reporting + +**Acceptance Criteria:** +- [ ] All 5 standards files created +- [ ] No factory-specific references +- [ ] All references point to claude-skills architecture +- [ ] Files pass markdown linting +- [ ] Standards are actionable + +**Deliverable:** Complete standards library + +--- + +### Afternoon Session (1 hour) + +#### Task 1.3: Commit Day 1 Work +**Estimated Time:** 30 minutes + +```bash +# Review changes +git status +git diff + +# Stage files +git add agents/ commands/ standards/ templates/ + +# Commit with conventional message +git commit -m "feat(foundation): create directory structure and standards library + +- Create root-level directories: agents/, commands/, standards/, templates/ +- Port 5 core standards from factory +- Adapt standards for claude-skills context +- Replace rr-* references with cs-* prefix + +Phase: 1 (Foundation) +Issues: #8, #9" + +# Push to dev branch +git push origin dev +``` + +#### Task 1.4: Update Issue Status +**Estimated Time:** 15 minutes + +```bash +# Close completed issues +gh issue close 8 --comment "✅ Directory structure created and verified" +gh issue close 9 --comment "✅ All 5 standards ported and adapted" + +# Move to next phase +gh issue edit 11 --remove-label "status:ready" --add-label "status:in-progress" +``` + +#### Task 1.5: Day 1 Validation +**Estimated Time:** 15 minutes + +- [ ] Run `/review` command (validate YAML, markdown) +- [ ] Verify directory structure exists +- [ ] Verify all 5 standards files created +- [ ] Check for broken links +- [ ] Markdown linting passes + +**End of Day 1 Status:** +- ✅ Foundation complete +- ✅ Ready for agent development +- ✅ Issues #8, #9 closed + +--- + +## Days 2-4: Agent Development (November 6-8, 2025) + +**Goal:** Implement 5 foundational agents + template + +**Strategy:** Can work on agents in parallel (different domains) + +### Day 2: Marketing Domain Agents + +#### Task 2.1: Create cs-content-creator Agent +**GitHub Issue:** [#11 - Create marketing agents](https://github.com/alirezarezvani/claude-skills/issues/11) +**Estimated Time:** 2 hours +**Priority:** P1 - HIGH + +**File:** `agents/marketing/cs-content-creator.md` + +**Structure to Create:** + +```yaml +--- +name: cs-content-creator +description: Create SEO-optimized marketing content with brand voice consistency +skills: content-creator +domain: marketing +model: sonnet +tools: [Read, Write, Bash, Grep, Glob] +--- + +# Content Creator Agent + +## Purpose +[1 paragraph describing what this agent does] + +## Skill Integration + +**Skill Location:** `../../marketing-skill/content-creator/` + +### Python Tools + +**Brand Voice Analyzer:** +```bash +python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt +python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt json +``` + +**SEO Optimizer:** +```bash +python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "primary keyword" +python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "primary keyword" "secondary,keywords" +``` + +### Knowledge Bases +- Brand Guidelines: `../../marketing-skill/content-creator/references/brand_guidelines.md` +- Content Frameworks: `../../marketing-skill/content-creator/references/content_frameworks.md` +- Social Media Optimization: `../../marketing-skill/content-creator/references/social_media_optimization.md` + +### Templates +- Content Calendar: `../../marketing-skill/content-creator/assets/content-calendar-template.md` +- Brand Voice Checklist: `../../marketing-skill/content-creator/assets/brand-voice-checklist.md` + +## Workflows + +### Workflow 1: Create Blog Post +[Detailed step-by-step workflow] + +### Workflow 2: Create Social Media Campaign +[Detailed step-by-step workflow] + +### Workflow 3: Analyze Brand Voice +[Detailed step-by-step workflow] + +## Integration Examples +[Concrete code examples] + +## Success Metrics +[How to measure effectiveness] + +## Related Agents +- cs-demand-gen-specialist (acquisition campaigns) +- cs-product-marketing (product launches) + +## References +- Skill Documentation: `../../marketing-skill/content-creator/SKILL.md` +- Standards: `../../standards/communication/communication-standards.md` +``` + +**Testing:** +```bash +# Test relative paths +cd agents/marketing +ls ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py +ls ../../marketing-skill/content-creator/references/brand_guidelines.md + +# Test Python tool execution +python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py \ + ../../marketing-skill/content-creator/SKILL.md + +# Back to root +cd ../.. +``` + +**Acceptance Criteria:** +- [ ] Complete YAML frontmatter +- [ ] All relative paths resolve +- [ ] 3 workflows documented +- [ ] Integration examples present +- [ ] Python tools tested +- [ ] No broken links + +--- + +#### Task 2.2: Create cs-demand-gen-specialist Agent +**GitHub Issue:** [#11 - Create marketing agents](https://github.com/alirezarezvani/claude-skills/issues/11) +**Estimated Time:** 2 hours +**Priority:** P1 - HIGH + +**File:** `agents/marketing/cs-demand-gen-specialist.md` + +**Structure:** Similar to cs-content-creator +- YAML frontmatter +- Skill integration: `../../marketing-skill/marketing-demand-acquisition/` +- Python tool: campaign_analyzer.py +- Workflows: Lead gen, conversion optimization, funnel analysis + +**Testing:** Same pattern as Task 2.1 + +--- + +### Day 3: C-Level Advisory Agents + +#### Task 3.1: Create cs-ceo-advisor Agent +**GitHub Issue:** [#12 - Create C-level agents](https://github.com/alirezarezvani/claude-skills/issues/12) +**Estimated Time:** 2 hours +**Priority:** P1 - HIGH + +**File:** `agents/c-level/cs-ceo-advisor.md` + +**Structure:** +- YAML frontmatter +- Skill integration: `../../c-level-advisor/ceo-advisor/` +- Python tools: strategic_framework_generator.py, scenario_planner.py, okr_tracker.py +- Workflows: Strategic planning, OKR setting, board deck prep, scenario analysis + +--- + +#### Task 3.2: Create cs-cto-advisor Agent +**GitHub Issue:** [#12 - Create C-level agents](https://github.com/alirezarezvani/claude-skills/issues/12) +**Estimated Time:** 2 hours +**Priority:** P1 - HIGH + +**File:** `agents/c-level/cs-cto-advisor.md` + +**Structure:** +- YAML frontmatter +- Skill integration: `../../c-level-advisor/cto-advisor/` +- Python tools: tech_stack_analyzer.py, architecture_auditor.py, team_velocity_tracker.py +- Workflows: Tech roadmap, build vs buy, tech debt, team scaling + +--- + +### Day 4: Product Agent + Template + +#### Task 4.1: Create cs-product-manager Agent +**GitHub Issue:** [#13 - Create product agent](https://github.com/alirezarezvani/claude-skills/issues/13) +**Estimated Time:** 1.5 hours +**Priority:** P1 - HIGH + +**File:** `agents/product/cs-product-manager.md` + +**Structure:** +- YAML frontmatter +- Skill integration: `../../product-team/product-manager-toolkit/` +- Python tools: rice_prioritizer.py, customer_interview_analyzer.py +- Workflows: Feature prioritization, interview analysis, roadmap generation, quarterly planning + +--- + +#### Task 4.2: Create Agent Template & Creation Guide +**GitHub Issue:** [#14 - Create agent template and guide](https://github.com/alirezarezvani/claude-skills/issues/14) +**Estimated Time:** 2 hours +**Priority:** P2 - MEDIUM + +**File 1:** `templates/agent-template.md` +- Complete structure with YAML frontmatter +- Placeholder sections +- Comments explaining each section +- Reference all 5 completed agents as examples + +**File 2:** `documentation/AGENT_CREATION_GUIDE.md` +- Step-by-step creation process +- Naming conventions (cs-* prefix, kebab-case) +- Relative path resolution guide +- Testing checklist +- Validation steps +- Troubleshooting section + +--- + +#### Task 4.3: Commit Days 2-4 Work +**Estimated Time:** 30 minutes + +```bash +# Review all agents +git status +git diff agents/ + +# Stage agents +git add agents/marketing/cs-content-creator.md +git add agents/marketing/cs-demand-gen-specialist.md +git add agents/c-level/cs-ceo-advisor.md +git add agents/c-level/cs-cto-advisor.md +git add agents/product/cs-product-manager.md +git add templates/agent-template.md +git add documentation/AGENT_CREATION_GUIDE.md + +# Commit +git commit -m "feat(agents): implement 5 foundational agents and template + +- Create cs-content-creator (marketing domain) +- Create cs-demand-gen-specialist (marketing domain) +- Create cs-ceo-advisor (C-level domain) +- Create cs-cto-advisor (C-level domain) +- Create cs-product-manager (product domain) +- Create agent template for future expansion +- Add comprehensive agent creation guide + +All agents tested with relative path resolution and Python tool execution. + +Phase: 2 (Agents) +Issues: #11, #12, #13, #14" + +# Push +git push origin dev +``` + +#### Task 4.4: Update Issue Status +```bash +# Close completed issues +gh issue close 11 --comment "✅ Marketing agents (cs-content-creator, cs-demand-gen-specialist) implemented and tested" +gh issue close 12 --comment "✅ C-level agents (cs-ceo-advisor, cs-cto-advisor) implemented and tested" +gh issue close 13 --comment "✅ Product agent (cs-product-manager) implemented and tested" +gh issue close 14 --comment "✅ Agent template and creation guide complete" + +# Start documentation phase +gh issue edit 15 --remove-label "status:backlog" --add-label "status:in-progress" +``` + +**End of Day 4 Status:** +- ✅ 5 agents implemented +- ✅ Agent template created +- ✅ Creation guide complete +- ✅ Issues #11, #12, #13, #14 closed + +--- + +## Days 5-6: Documentation & Testing (November 11-12, 2025) + +**Goal:** Update project documentation and validate all deliverables + +### Day 5: Documentation Updates + +#### Task 5.1: Update README.md +**GitHub Issue:** [#15 - Update project documentation](https://github.com/alirezarezvani/claude-skills/issues/15) +**Estimated Time:** 1 hour + +**Sections to Add:** + +1. **Quick Start** (add near top) +```markdown +## 🚀 Quick Start + +### Installation +```bash +git clone https://github.com/alirezarezvani/claude-skills.git +cd claude-skills +# TODO: ./install.sh (Phase 3) +``` + +### Use Your First Agent +```bash +# Invoke content creator agent +claude-code --agent cs-content-creator + +# Or use directly in workflows +``` + +See [INSTALL.md](INSTALL.md) for detailed setup. +``` + +2. **Agent Catalog** (new section) +```markdown +## 🤖 Agent Catalog + +Specialized agents that orchestrate skills and provide guided workflows. + +| Agent | Domain | Skills Used | Description | +|-------|--------|-------------|-------------| +| [cs-content-creator](agents/marketing/cs-content-creator.md) | Marketing | content-creator | SEO-optimized content with brand voice | +| [cs-demand-gen-specialist](agents/marketing/cs-demand-gen-specialist.md) | Marketing | marketing-demand-acquisition | Lead gen and conversion optimization | +| [cs-ceo-advisor](agents/c-level/cs-ceo-advisor.md) | C-Level | ceo-advisor | Strategic planning and OKR setting | +| [cs-cto-advisor](agents/c-level/cs-cto-advisor.md) | C-Level | cto-advisor | Tech roadmap and architecture decisions | +| [cs-product-manager](agents/product/cs-product-manager.md) | Product | product-manager-toolkit | RICE prioritization and roadmapping | + +[View all 42 skills →](README.md#skills-overview) +``` + +3. **Skills vs Agents** (explanation section) +```markdown +## 💡 Skills vs Agents + +**Skills** = Python tools + knowledge bases + templates +- 42 production-ready skills +- 97 automation tools +- Domain expertise packaged + +**Agents** = Workflow orchestrators +- Invoke skills intelligently +- Guide multi-step processes +- Coordinate tools and knowledge + +**Example:** cs-content-creator agent uses the content-creator skill's Python tools (brand_voice_analyzer.py, seo_optimizer.py) plus knowledge bases (brand guidelines, SEO frameworks) to guide you through content creation. +``` + +--- + +#### Task 5.2: Create INSTALL.md +**GitHub Issue:** [#15 - Update project documentation](https://github.com/alirezarezvani/claude-skills/issues/15) +**Estimated Time:** 45 minutes + +**Contents:** +- Prerequisites (Claude Code CLI, Python 3.8+, Git) +- Installation steps (clone + manual setup until install.sh ready) +- Verification commands +- Troubleshooting section + +--- + +#### Task 5.3: Create USAGE.md +**GitHub Issue:** [#15 - Update project documentation](https://github.com/alirezarezvani/claude-skills/issues/15) +**Estimated Time:** 1 hour + +**Contents:** +- Agent invocation examples (all 5 agents) +- Multi-agent coordination patterns +- Skill + Agent workflow examples +- Best practices +- Tips and tricks + +--- + +#### Task 5.4: Update CLAUDE.md +**GitHub Issue:** [#15 - Update project documentation](https://github.com/alirezarezvani/claude-skills/issues/15) +**Estimated Time:** 30 minutes + +**Updates:** +- Architecture overview (new agents/ directory) +- Directory tree diagram +- Agent integration architecture section +- cs-* prefix convention +- Relative path patterns + +--- + +### Day 6: Testing & Validation + +#### Task 6.1: Comprehensive Testing +**GitHub Issue:** [#16 - Phase 1-2 Testing and Validation](https://github.com/alirezarezvani/claude-skills/issues/16) +**Estimated Time:** 2 hours + +**Test Categories:** + +1. **Directory Structure** (15 min) +```bash +# Verify all directories exist +ls agents/marketing agents/c-level agents/product +ls commands +ls standards/communication standards/quality standards/git standards/documentation standards/security +ls templates +``` + +2. **Standards Validation** (15 min) +```bash +# Check all standards files +ls standards/*/ +# Verify no factory references +grep -r "rr-" standards/ || echo "✅ No rr-* references" +grep -r "factory" standards/ || echo "✅ No factory references" +# Markdown linting +yamllint standards/ +``` + +3. **Agent Validation** (30 min) +```bash +# Check all agent files exist +ls agents/marketing/cs-content-creator.md +ls agents/marketing/cs-demand-gen-specialist.md +ls agents/c-level/cs-ceo-advisor.md +ls agents/c-level/cs-cto-advisor.md +ls agents/product/cs-product-manager.md + +# Validate YAML frontmatter (check each file) +head -20 agents/marketing/cs-content-creator.md # Should show valid YAML +``` + +4. **Path Resolution Testing** (30 min) +```bash +# Test from each agent directory +cd agents/marketing +python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py --help +ls ../../marketing-skill/content-creator/references/brand_guidelines.md + +cd ../c-level +ls ../../c-level-advisor/ceo-advisor/scripts/ + +cd ../product +python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py --help + +cd ../.. +``` + +5. **Python Tool Execution** (30 min) +```bash +# Run actual tools to verify they work +python marketing-skill/content-creator/scripts/brand_voice_analyzer.py CLAUDE.md + +python marketing-skill/content-creator/scripts/seo_optimizer.py README.md "claude skills" + +python product-team/product-manager-toolkit/scripts/rice_prioritizer.py --help +``` + +6. **Documentation Quality** (15 min) +```bash +# Check for broken links +# Verify markdown linting passes +yamllint agents/**/*.md +yamllint documentation/**/*.md + +# Verify all required sections present in each agent +grep -l "## Purpose" agents/**/*.md +grep -l "## Skill Integration" agents/**/*.md +grep -l "## Workflows" agents/**/*.md +``` + +--- + +#### Task 6.2: Quality Gates +**Estimated Time:** 30 minutes + +```bash +# Run quality checks +/review + +# Run security scan +/security-scan + +# Verify all pass +``` + +--- + +#### Task 6.3: Final Validation Checklist +**Estimated Time:** 15 minutes + +- [ ] All 10 directories created +- [ ] 5 standards files ported and validated +- [ ] 5 agents implemented and tested +- [ ] All relative paths work +- [ ] All Python tools executable +- [ ] Agent template complete +- [ ] Creation guide actionable +- [ ] README.md updated +- [ ] INSTALL.md created +- [ ] USAGE.md created +- [ ] CLAUDE.md updated +- [ ] All quality gates pass +- [ ] No broken links + +--- + +#### Task 6.4: Final Commit & PR +**Estimated Time:** 30 minutes + +```bash +# Stage documentation +git add README.md INSTALL.md USAGE.md CLAUDE.md + +# Commit documentation +git commit -m "docs: update project documentation for agent integration + +- Update README with Quick Start and Agent Catalog +- Create INSTALL.md with setup instructions +- Create USAGE.md with comprehensive examples +- Update CLAUDE.md with architecture changes + +Phase: 4 (Documentation) +Issue: #15" + +# Push +git push origin dev + +# Create PR for review +gh pr create \ + --base main \ + --head dev \ + --title "feat: Skill-Agent Integration Phase 1-2 Complete" \ + --body "$(cat <<'EOF' +## Summary + +Complete Phase 1-2 implementation of skill-agent integration for claude-code-skills. + +## What's New + +### Foundation (Phase 1) +- ✅ Root-level directory structure (agents/, commands/, standards/, templates/) +- ✅ 5 core standards ported from factory and adapted + +### Agents (Phase 2) +- ✅ cs-content-creator (marketing) +- ✅ cs-demand-gen-specialist (marketing) +- ✅ cs-ceo-advisor (C-level) +- ✅ cs-cto-advisor (C-level) +- ✅ cs-product-manager (product) + +### Templates & Docs +- ✅ Agent template for future expansion +- ✅ Agent creation guide +- ✅ Updated README, INSTALL, USAGE, CLAUDE + +## Testing + +- ✅ All relative paths resolve correctly +- ✅ All Python tools execute successfully +- ✅ Quality gates pass (/review, /security-scan) +- ✅ No broken links +- ✅ Comprehensive testing complete + +## Issues Closed + +Closes #8, #9, #11, #12, #13, #14, #15, #16 + +## Milestone + +Completes: [Skill-Agent Integration v1.0](https://github.com/alirezarezvani/claude-skills/milestone/1) Phase 1-2 + +## Next Steps + +- Phase 3: Installation scripts (install.sh, uninstall.sh) +- Phase 4-5: Already complete (documentation & testing) +- Phase 6-7: Plugin marketplace submission + +## Reviewers + +Please review: +- [ ] Directory structure is clean +- [ ] Agent implementations are comprehensive +- [ ] Documentation is clear and actionable +- [ ] All quality checks pass +EOF +)" +``` + +--- + +#### Task 6.5: Close All Issues +**Estimated Time:** 15 minutes + +```bash +# Close remaining issues +gh issue close 15 --comment "✅ All documentation updated (README, INSTALL, USAGE, CLAUDE)" +gh issue close 16 --comment "✅ Comprehensive testing complete - all quality gates pass" + +# Verify all closed +gh issue list --milestone "Skill-Agent Integration v1.0" --state open +# Should show 0 open issues for Phase 1-2 +``` + +**End of Day 6 Status:** +- ✅ All documentation updated +- ✅ Comprehensive testing complete +- ✅ All quality gates pass +- ✅ PR created for review +- ✅ All Phase 1-2 issues closed + +--- + +## Sprint Completion Summary + +### Deliverables + +**Phase 1: Foundation** +- ✅ 10 directories created +- ✅ 5 standards ported + +**Phase 2: Agents** +- ✅ 5 agents implemented +- ✅ Agent template created +- ✅ Creation guide written + +**Phase 4: Documentation** +- ✅ README updated +- ✅ INSTALL.md created +- ✅ USAGE.md created +- ✅ CLAUDE.md updated + +**Phase 5: Testing** +- ✅ Comprehensive validation +- ✅ All quality gates pass + +### Metrics + +- **Issues Completed:** 8 (all Phase 1-2 issues) +- **Files Created:** 17 (10 dirs, 5 standards, 5 agents, 1 template, 1 guide, 4 docs) +- **Lines of Code:** ~3000+ (agent files, documentation) +- **Test Coverage:** 100% (all agents tested) +- **Quality Score:** 100% (all gates pass) + +### Next Sprint Planning + +**Phase 3: Installation System** +- Create install.sh (interactive) +- Create uninstall.sh +- Backwards compatibility + +**Phase 6-7: Plugin Creation** +- Research marketplace requirements +- Design plugin.yaml manifest +- Package for distribution +- Submit to Anthropic marketplace + +--- + +## Sprint Retrospective Notes + +### What Went Well +- Clear implementation plan +- Comprehensive GitHub issues +- Strong foundation established +- Template enables future expansion + +### Challenges Encountered +- [To be filled during sprint] + +### Lessons Learned +- [To be filled during sprint] + +### Process Improvements +- [To be filled during sprint] + +--- + +## References + +- **Implementation Plan:** `documentation/implementation/implementation-plan-november-2025.md` +- **Sprint Context:** `documentation/delivery/sprint-11-05-2025/context.md` +- **GitHub Issues:** [#8](https://github.com/alirezarezvani/claude-skills/issues/8), [#9](https://github.com/alirezarezvani/claude-skills/issues/9), [#11](https://github.com/alirezarezvani/claude-skills/issues/11), [#12](https://github.com/alirezarezvani/claude-skills/issues/12), [#13](https://github.com/alirezarezvani/claude-skills/issues/13), [#14](https://github.com/alirezarezvani/claude-skills/issues/14), [#15](https://github.com/alirezarezvani/claude-skills/issues/15), [#16](https://github.com/alirezarezvani/claude-skills/issues/16) +- **Milestone:** [Skill-Agent Integration v1.0](https://github.com/alirezarezvani/claude-skills/milestone/1) +- **Project Board:** [Project #9](https://github.com/users/alirezarezvani/projects/9) + +--- + +**Sprint Status:** 🎯 Ready to Start +**Next Action:** Begin Day 1 - Task 1.1 (Create Directory Structure) +**Document Version:** 1.0 +**Created:** November 5, 2025 +**Last Updated:** November 5, 2025 diff --git a/standards/communication/.gitkeep b/standards/communication/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/standards/communication/communication-standards.md b/standards/communication/communication-standards.md new file mode 100644 index 0000000..67f9647 --- /dev/null +++ b/standards/communication/communication-standards.md @@ -0,0 +1,38 @@ +# Communication Standards + +## Core Requirements + +- **Absolute Honesty**: Direct assessments without diplomatic cushioning +- **Zero Fluff**: Eliminate vague statements and buzzwords +- **Pragmatic Focus**: Every suggestion must be immediately actionable +- **Critical Analysis**: Challenge assumptions and identify flaws before responding +- **Always Ask for Clarification**: Never assume or fill gaps with generic advice + +## Solution Standards + +- **File Economy**: Edit existing files instead of creating new ones when possible +- **Anti-Overengineering**: Choose simple, direct solutions over elaborate architectures + +## Response Protocol + +1. **Pre-Response Check**: Verify answer is specific and actionable +2. **Critical Review**: Identify and address solution weaknesses +3. **Implementation Reality**: Confirm feasibility within stated constraints + +## Prohibited Responses + +- Generic praise without technical analysis +- Vague suggestions without clear reasoning +- Advice without implementation details +- Assumptions when requirements are unclear +- Over-engineered solutions for simple problems + +## Standard Structure + +1. Direct assessment following user specifications +2. Critical analysis with potential issues +3. Step-by-step recommendations (edit vs. create approach) +4. Resource requirements and code organization +5. Documentation and maintenance considerations + +**Remember**: This repository provides production-ready skills and agent workflows. Focus on helping users implement, customize, and extend these skills for their projects. Agents (cs-* prefix) should orchestrate skills effectively, provide clear workflows, and maintain the high quality standards of the skill library. Always use the current date when creating files or examples. diff --git a/standards/documentation/.gitkeep b/standards/documentation/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/standards/documentation/documentation-standards.md b/standards/documentation/documentation-standards.md new file mode 100644 index 0000000..1e0faaf --- /dev/null +++ b/standards/documentation/documentation-standards.md @@ -0,0 +1,545 @@ +# Documentation Standards + +## Core Principles + +### **1. Living Documentation** +- Documentation stays current with code +- Update docs in the same PR as code changes +- Living docs (README, CLAUDE, AGENTS) updated regularly +- Outdated information removed promptly + +### **2. Clarity & Accessibility** +- Write for beginners, not experts +- Use simple, clear language +- Provide examples for all concepts +- Include troubleshooting sections + +### **3. Structure & Consistency** +- Follow established templates +- Use consistent formatting +- Maintain clear hierarchy +- Keep related content together + +## File Naming Conventions + +### **General Rules** + +```yaml +# Markdown files +README.md # Repository root (UPPERCASE) +CLAUDE.md # Repository root (UPPERCASE) +AGENTS.md # Repository root (UPPERCASE) +CHANGELOG.md # Repository root (UPPERCASE) +LICENSE # Repository root (no extension) + +# Other documentation (lowercase with hyphens) +installation-guide.md +user-guide.md +api-reference.md +troubleshooting.md +``` + +### **Directory-Specific Naming** + +```yaml +# Agents (lowercase with hyphens) +agents/marketing/cs-content-creator.md +agents/c-level/cs-ceo-advisor.md + +# Skills (lowercase, no hyphens in folder names) +marketing-skill/content-creator/SKILL.md + +# Standards (lowercase with hyphens) +standards/communication/communication-standards.md + +# Documentation (lowercase with hyphens) +documentation/implementation/implementation-plan-november-2025.md +documentation/delivery/sprint-11-05-2025/context.md +``` + +## Markdown Formatting Standards + +### **1. Headings** + +```markdown +# H1 - Document Title (only one per file) + +## H2 - Major Sections + +### H3 - Subsections + +#### H4 - Details + +**Don't skip heading levels!** +✅ H1 → H2 → H3 +❌ H1 → H3 (skips H2) +``` + +### **2. Lists** + +```markdown +# Unordered lists +- Item 1 +- Item 2 + - Sub-item 2.1 + - Sub-item 2.2 +- Item 3 + +# Ordered lists +1. First step +2. Second step +3. Third step + +# Task lists +- [ ] Incomplete task +- [x] Completed task +``` + +### **3. Code Blocks** + +```markdown +# Inline code +Use `code` for commands, filenames, and variables. + +# Code blocks with syntax highlighting +\`\`\`bash +# Bash commands +git commit -m "feat(agents): implement cs-content-creator" +\`\`\` + +\`\`\`python +# Python code +def analyze_content(text: str) -> Dict[str, Any]: + return {"score": 0.85} +\`\`\` + +\`\`\`yaml +# YAML configuration +name: cs-content-creator +domain: marketing +\`\`\` +``` + +### **4. Links** + +```markdown +# External links +[Link text](https://example.com) + +# Internal links (relative paths) +[Agent catalog](agents/README.md) +[Installation guide](INSTALL.md) + +# Link to specific heading +[See quality standards](#quality-standards) + +# Reference-style links (for repeated URLs) +[Claude Code][1] +[GitHub][2] + +[1]: https://claude.com/code +[2]: https://github.com +``` + +### **5. Images** + +```markdown +# Standard image +![Alt text describing image](path/to/image.png) + +# Image with title +![Alt text](image.png "Image title") + +# Linked image +[![Alt text](image.png)](https://link-destination.com) + +**Always provide alt text for accessibility!** +``` + +### **6. Tables** + +```markdown +| Column 1 | Column 2 | Column 3 | +|----------|----------|----------| +| Data 1 | Data 2 | Data 3 | +| Data 4 | Data 5 | Data 6 | + +# Alignment +| Left | Center | Right | +|:-----|:------:|------:| +| L1 | C1 | R1 | +``` + +### **7. Emphasis** + +```markdown +*Italic text* or _italic text_ +**Bold text** or __bold text__ +***Bold and italic*** or ___bold and italic___ +~~Strikethrough~~ + +Use **bold** for emphasis, *italic* for definitions. +``` + +### **8. Blockquotes** + +```markdown +> Single line quote + +> Multi-line quote +> continues here +> and here + +> **Note:** Important information +> highlighted in a quote block +``` + +### **9. Horizontal Rules** + +```markdown +--- + +Use sparingly to separate major sections. +``` + +## Document Structure Templates + +### **Agent Documentation (agents/*/cs-*.md)** + +```markdown +--- +name: cs-agent-name +description: One-line description +skills: skill-folder-name +domain: domain-name +model: sonnet +tools: [Read, Write, Bash, Grep, Glob] +--- + +# Agent Name + +## Purpose +[1-2 paragraphs describing what this agent does] + +## Skill Integration + +**Skill Location:** `../../skill-folder/` + +### Python Tools +[List with usage examples] + +### Knowledge Bases +[List with relative paths] + +### Templates +[List with relative paths] + +## Workflows + +### Workflow 1: [Name] +[Step-by-step process] + +### Workflow 2: [Name] +[Step-by-step process] + +## Integration Examples +[Concrete examples with code] + +## Success Metrics +[How to measure effectiveness] + +## Related Agents +[Links to related agents] + +## References +[Links to documentation] +``` + +### **README.md Structure** + +```markdown +# Project Title + +[1-sentence project description] + +## Quick Start + +[Installation and first use - 30 seconds] + +## Features + +- Feature 1 +- Feature 2 +- Feature 3 + +## Installation + +[Detailed installation steps] + +## Usage + +[Basic usage examples] + +## Documentation + +- [Installation Guide](INSTALL.md) +- [Usage Guide](USAGE.md) +- [Agent Catalog](agents/README.md) + +## Contributing + +[Contribution guidelines] + +## License + +[License information] +``` + +### **SKILL.md Structure** + +```markdown +# Skill Name + +[1-2 paragraph description] + +## What This Skill Does + +[Clear explanation of purpose and value] + +## Contents + +- Python Tools (X scripts) +- Knowledge Bases (X references) +- Templates (X templates) + +## Python Automation Tools + +### Tool 1: [Name] +**Purpose:** [What it does] +**Usage:** +\`\`\`bash +python scripts/tool-name.py input.txt +\`\`\` + +## Knowledge Bases + +### Reference 1: [Name] +**Location:** `references/file-name.md` +**Content:** [What's inside] + +## Templates + +### Template 1: [Name] +**Location:** `assets/template-name.md` +**Use Case:** [When to use] + +## Examples + +[Real-world usage examples] + +## Requirements + +- Python 3.8+ +- Standard library only (or list dependencies) + +## Installation + +[How to use this skill] + +## Related Skills + +[Links to related skills] +``` + +## Living Documentation + +### **Files That Must Stay Current** + +```yaml +repository_root: + README.md: + update_frequency: "Every major feature" + purpose: "Primary project documentation" + audience: "All users" + + CLAUDE.md: + update_frequency: "Every structural change" + purpose: "AI context and architecture" + audience: "Claude Code and developers" + + AGENTS.md: + update_frequency: "Every agent added/modified" + purpose: "Agent catalog and reference" + audience: "Agent developers" + + CHANGELOG.md: + update_frequency: "Every release" + purpose: "Version history and changes" + audience: "All users" +``` + +### **Update Triggers** + +```yaml +update_readme_when: + - New skill added + - New agent implemented + - Installation process changes + - Major feature added + +update_claude_md_when: + - Directory structure changes + - Architecture changes + - New standards added + - Agent integration patterns change + +update_agents_md_when: + - New agent created + - Agent modified + - Agent deprecated + - Agent template changes +``` + +## Quality Checklist + +### **Pre-Commit Documentation Review** + +```yaml +content_quality: + - [ ] All headings follow hierarchy (no skipped levels) + - [ ] All code blocks have syntax highlighting + - [ ] All links work (no 404s) + - [ ] All images have alt text + - [ ] No spelling errors + - [ ] Grammar is correct + - [ ] Examples are tested and working + +formatting: + - [ ] Consistent heading style + - [ ] Consistent list formatting + - [ ] Consistent code block style + - [ ] No trailing whitespace + - [ ] Single blank line between sections + - [ ] Proper indentation + +accessibility: + - [ ] Alt text describes images meaningfully + - [ ] Link text is descriptive (not "click here") + - [ ] Heading hierarchy is logical + - [ ] Tables have headers + - [ ] Color is not the only way to convey information +``` + +### **Link Validation** + +```bash +# Check for broken markdown links +find . -name "*.md" -exec grep -l "](.*)" {} \; | while read file; do + echo "Checking links in: $file" + # Manual check or use markdown-link-check tool +done +``` + +## Documentation Best Practices + +### **Do's** + +- ✅ Write for the target audience +- ✅ Use clear, simple language +- ✅ Provide concrete examples +- ✅ Include screenshots where helpful +- ✅ Update docs with code changes +- ✅ Link to related documentation +- ✅ Use consistent terminology +- ✅ Test all code examples + +### **Don'ts** + +- ❌ Assume prior knowledge +- ❌ Use jargon without explanation +- ❌ Write vague instructions +- ❌ Skip error scenarios +- ❌ Let docs get stale +- ❌ Use "click here" as link text +- ❌ Skip proofreading +- ❌ Forget about mobile users + +## Special Documentation Types + +### **API Documentation** + +```markdown +## Function Name + +**Purpose:** What this function does + +**Parameters:** +- `param1` (type): Description +- `param2` (type, optional): Description, default: value + +**Returns:** +- (type): Description of return value + +**Raises:** +- `ExceptionName`: When this is raised + +**Example:** +\`\`\`python +result = function_name(param1="value", param2=42) +print(result) +# Output: expected output +\`\`\` +``` + +### **Troubleshooting Guide** + +```markdown +## Problem: [Describe the problem] + +**Symptoms:** +- Symptom 1 +- Symptom 2 + +**Cause:** +[What causes this issue] + +**Solution:** +1. Step 1 +2. Step 2 +3. Step 3 + +**Verification:** +[How to confirm it's fixed] +``` + +### **Decision Records** + +```markdown +# Decision: [Title] + +**Date:** YYYY-MM-DD +**Status:** Accepted | Rejected | Superseded + +## Context +[What's the situation?] + +## Decision +[What did we decide?] + +## Rationale +[Why did we decide this?] + +## Consequences +[What are the impacts?] + +## Alternatives Considered +1. Alternative 1 - [Why rejected] +2. Alternative 2 - [Why rejected] +``` + +--- + +**Focus**: Markdown quality, structure consistency, living documentation +**Updated**: November 2025 +**Review**: Monthly documentation quality assessment +**Compliance**: Markdown standards, accessibility guidelines diff --git a/standards/git/.gitkeep b/standards/git/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/standards/git/git-workflow-standards.md b/standards/git/git-workflow-standards.md new file mode 100644 index 0000000..0ce1c94 --- /dev/null +++ b/standards/git/git-workflow-standards.md @@ -0,0 +1,439 @@ +# Git Workflow Standards + +## Core Principles + +### **1. Conventional Commits** +- All commits follow conventional commits specification +- Enable automated changelog generation +- Clear categorization of all changes +- Explicit marking of breaking changes + +### **2. Semantic Versioning** +- Automated versioning based on commit types +- MAJOR version: BREAKING CHANGE +- MINOR version: feat type commits +- PATCH version: fix type commits + +### **3. Branch Protection** +- Main branch requires review +- All quality gates must pass +- No force pushes to main +- Signed commits recommended + +## Conventional Commits Specification + +### **Commit Message Structure** + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +### **Standard Types** + +```yaml +feat: # New features (agents, skills, tools) +fix: # Bug fixes +docs: # Documentation only changes +style: # Formatting changes (no functional impact) +refactor: # Code restructuring without feature changes +perf: # Performance improvements +test: # Adding or correcting tests +chore: # Maintenance tasks (dependencies, build) +ci: # CI/CD configuration changes +``` + +### **Examples** + +```bash +# New agent implementation +feat(agents): implement cs-content-creator agent + +# Bug fix in Python tool +fix(seo-optimizer): correct keyword density calculation + +# Documentation update +docs(README): add agent catalog section + +# Breaking change +feat(agents)!: replace agent template structure + +BREAKING CHANGE: agent frontmatter now requires 'tools' field +``` + +### **Scopes for Claude Skills** + +```yaml +Common Scopes: + agents: # Agent implementation + skills: # Skill packages + standards: # Standards library + templates: # Templates + docs: # Documentation + foundation: # Core infrastructure + marketing: # Marketing domain + c-level: # C-level domain + product: # Product domain + engineering: # Engineering domain + ra-qm: # RA/QM domain +``` + +## Branch Strategy + +### **Branch Naming Conventions** + +```yaml +# Feature branches (agent/skill development) +feature/agents-{name}: # New agent implementation +feature/skills-{name}: # New skill package +feature/{domain}-{component}: # Domain-specific features + +# Documentation branches +docs/{component}: # Documentation updates +docs/standards-{name}: # Standards library updates + +# Bug fixes +fix/{issue-number}-{description}: # Bug fixes + +# Hotfixes (critical production issues) +hotfix/{issue}-{description}: # Emergency fixes + +# Test branches +test/{feature}: # Testing and validation +``` + +### **Examples** + +```bash +# Create feature branch for new agent +git checkout -b feature/agents-ceo-advisor + +# Create documentation branch +git checkout -b docs/installation-guide + +# Create fix branch +git checkout -b fix/23-broken-relative-paths + +# Create test branch +git checkout -b test/agent-path-resolution +``` + +## Workflow Process + +### **1. Development Workflow** + +```bash +# Start new feature +git checkout -b feature/agents-product-manager + +# Make changes +# ... edit files ... + +# Stage changes +git add agents/product/cs-product-manager.md + +# Commit with conventional message +git commit -m "feat(agents): implement cs-product-manager agent + +- Add YAML frontmatter +- Document RICE prioritization workflow +- Add interview analysis integration +- Test relative path resolution + +Phase: 2.3 +Issue: #13" + +# Push to remote +git push origin feature/agents-product-manager +``` + +### **2. Pull Request Workflow** + +```bash +# Create PR using gh CLI +gh pr create \ + --base main \ + --head feature/agents-product-manager \ + --title "feat(agents): implement cs-product-manager agent" \ + --body "Closes #13 + +## Summary +Implements product management agent with RICE prioritization and interview analysis. + +## Testing +- [x] Relative paths resolve correctly +- [x] Python tools execute successfully +- [x] Workflows documented +- [x] Quality gates pass" +``` + +### **3. Review & Merge** + +```bash +# After review approval +gh pr merge feature/agents-product-manager \ + --squash \ + --delete-branch +``` + +### **4. Release Workflow** + +```bash +# Create release with semantic versioning +git tag v1.0.0-agents +git push origin v1.0.0-agents + +# GitHub Actions automatically creates release with changelog +``` + +## Commit Message Templates + +### **For Agent Implementation** + +``` +feat(agents): implement cs-{agent-name} + +- Add YAML frontmatter with required fields +- Document {number} workflows +- Add integration examples +- Test Python tool execution +- Verify relative path resolution + +Phase: {phase-number} +Issue: #{issue-number} +``` + +### **For Skill Development** + +``` +feat(skills): add {skill-name} to {domain} domain + +- Create skill directory structure +- Implement {number} Python automation tools +- Add knowledge base references +- Create user templates + +Domain: {domain} +Issue: #{issue-number} +``` + +### **For Standards Updates** + +``` +docs(standards): update {standard-name} for {context} + +- Adapt for claude-skills context +- Remove factory-specific references +- Add agent-specific guidelines +- Update examples + +Issue: #{issue-number} +``` + +### **For Bug Fixes** + +``` +fix({scope}): resolve {issue-description} + +Problem: {what was broken} +Solution: {what was fixed} +Impact: {who/what this affects} + +Fixes #{issue-number} +``` + +## Git Hooks + +### **Pre-commit Hook** + +```bash +#!/bin/bash +# .git/hooks/pre-commit + +echo "Running pre-commit checks..." + +# Check for secrets +if git diff --cached | grep -iE '(api[_-]?key|secret|password|token).*=.*[^x{5}]'; then + echo "❌ Potential secret detected in commit" + exit 1 +fi + +# Validate Python syntax +python -m compileall $(git diff --cached --name-only --diff-filter=ACM | grep '\.py$') +if [ $? -ne 0 ]; then + echo "❌ Python syntax errors detected" + exit 1 +fi + +echo "✅ Pre-commit checks passed" +``` + +### **Commit-msg Hook** + +```bash +#!/bin/bash +# .git/hooks/commit-msg + +# Validate conventional commit format +commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\([a-z-]+\))?(!)?:\ .{1,}' + +if ! head -1 "$1" | grep -qE "$commit_regex"; then + echo "❌ Commit message does not follow conventional commits format" + echo "Format: [(scope)]: " + echo "Example: feat(agents): implement cs-product-manager" + exit 1 +fi + +echo "✅ Commit message format valid" +``` + +## Quality Gates Integration + +### **Pre-push Validation** + +```bash +#!/bin/bash +# .git/hooks/pre-push + +echo "Running pre-push validation..." + +# Run quality checks +/review + +# Check for TODO comments in production code +if git diff origin/main...HEAD | grep -i "TODO"; then + echo "⚠️ TODO comments found - consider addressing before push" +fi + +echo "✅ Pre-push validation complete" +``` + +## Branch Protection Rules + +### **Main Branch Protection** + +```yaml +branch_protection: + required_status_checks: + strict: true + contexts: + - "ci-quality-gate" + - "claude-review" + + required_pull_request_reviews: + required_approving_review_count: 1 + dismiss_stale_reviews: true + require_code_owner_reviews: false + + enforce_admins: true + required_conversation_resolution: true + allow_force_pushes: false + allow_deletions: false +``` + +## Common Workflows + +### **Hotfix Process** + +```bash +# Create hotfix branch from main +git checkout main +git pull origin main +git checkout -b hotfix/critical-path-resolution + +# Fix issue +# ... make changes ... + +# Commit with high priority +git commit -m "fix(agents)!: resolve critical path resolution failure + +BREAKING CHANGE: agent path resolution now requires absolute project root + +Fixes #42 +Priority: P0" + +# Create PR with hotfix label +gh pr create --label "P0,hotfix" --base main + +# After merge, tag immediately +git tag v1.0.1-hotfix +git push origin v1.0.1-hotfix +``` + +### **Multi-Agent Coordination** + +```bash +# Coordinating changes across multiple agents +git checkout -b feature/update-all-marketing-agents + +# Update cs-content-creator +git add agents/marketing/cs-content-creator.md +git commit -m "feat(agents): enhance cs-content-creator workflows" + +# Update cs-demand-gen-specialist +git add agents/marketing/cs-demand-gen-specialist.md +git commit -m "feat(agents): enhance cs-demand-gen-specialist workflows" + +# Push coordinated changes +git push origin feature/update-all-marketing-agents +``` + +## Best Practices + +### **Do's** + +- ✅ Use conventional commit format for all commits +- ✅ Reference issue numbers in commit messages +- ✅ Keep commits atomic (one logical change per commit) +- ✅ Write clear, descriptive commit messages +- ✅ Test changes before committing +- ✅ Pull before pushing to avoid conflicts +- ✅ Use feature branches for all changes +- ✅ Delete branches after merging + +### **Don'ts** + +- ❌ Commit directly to main (use PRs) +- ❌ Force push to shared branches +- ❌ Commit secrets or credentials +- ❌ Mix multiple unrelated changes in one commit +- ❌ Use vague commit messages ("fix stuff", "updates") +- ❌ Skip quality checks +- ❌ Leave branches unmerged for extended periods + +## Emergency Procedures + +### **Rollback Commit** + +```bash +# Revert the last commit (creates new commit) +git revert HEAD + +# Revert specific commit +git revert + +# Force rollback (use with caution!) +git reset --hard HEAD~1 +git push origin main --force # Only if absolutely necessary! +``` + +### **Fix Bad Commit Message** + +```bash +# Amend last commit message (before push) +git commit --amend -m "feat(agents): corrected commit message" + +# After push (creates new commit) +git revert HEAD +git commit -m "feat(agents): correct implementation with proper message" +``` + +--- + +**Standard**: Conventional Commits v1.0.0 +**Versioning**: Semantic Versioning v2.0.0 +**Updated**: November 2025 +**Review**: Monthly git workflow assessment diff --git a/standards/quality/.gitkeep b/standards/quality/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/standards/quality/quality-standards.md b/standards/quality/quality-standards.md new file mode 100644 index 0000000..28ed606 --- /dev/null +++ b/standards/quality/quality-standards.md @@ -0,0 +1,319 @@ +# Quality Standards + +## Core Quality Principles + +### **1. Quality-First Completion** +- **Zero Defect Handoff:** No work considered complete with known quality issues +- **Comprehensive Validation:** All acceptance criteria verified through testing +- **Path Resolution:** All relative paths validated and working +- **Tool Execution:** All Python tools tested and executing correctly + +### **2. Testing Standards** +- **Python Tools:** All automation tools must execute without errors +- **Agent Workflows:** Agent markdown files validated for completeness +- **Integration Testing:** Agent-to-skill integration verified +- **Documentation Quality:** All documentation clear, accurate, and actionable + +### **3. Code Quality** +- **Python Standards:** PEP 8 compliance for all Python scripts +- **No Hardcoded Secrets:** Use environment variables or configuration files +- **Error Handling:** Proper exception handling in all tools +- **Type Hints:** Use type annotations for Python functions + +## Universal Completion Criteria (ALL TASKS) + +```yaml +functional_requirements: + - [ ] All acceptance criteria satisfied with documented verification + - [ ] Feature functionality validated in target environments + - [ ] Edge cases identified and handled appropriately + - [ ] Error scenarios tested with proper error handling + - [ ] Integration points tested and validated + +quality_standards: + - [ ] Code review completed with documented feedback + - [ ] Automated tests passing where applicable + - [ ] Manual testing completed for user-facing functionality + - [ ] Documentation updated with changes + - [ ] No broken links or missing references + +documentation_requirements: + - [ ] Technical documentation updated with implementation details + - [ ] User documentation updated with new functionality guidance + - [ ] Change documentation prepared with impact analysis + - [ ] Handoff documentation prepared with clear next steps +``` + +## Agent-Specific Quality Gates + +### **Agent Implementation Standards** + +```yaml +agent_quality_validation: + yaml_frontmatter: + - [ ] Valid YAML syntax (no parsing errors) + - [ ] All required fields present (name, description, skills, domain, model, tools) + - [ ] cs-* prefix used for agent naming + - [ ] Domain correctly categorized + + skill_integration: + - [ ] Relative paths resolve correctly (../../ pattern) + - [ ] Skill location documented and accessible + - [ ] Python tools referenced with correct paths + - [ ] Knowledge bases referenced with correct paths + - [ ] Templates referenced with correct paths + + workflow_documentation: + - [ ] Minimum 3 workflows documented + - [ ] Each workflow has clear step-by-step instructions + - [ ] Integration examples provided + - [ ] Success metrics defined + - [ ] Related agents cross-referenced + + testing_requirements: + - [ ] Python tool execution tested from agent context + - [ ] Relative path resolution verified + - [ ] Knowledge base files accessible + - [ ] All examples in documentation work + - [ ] No broken markdown links +``` + +## Python Tool Quality Standards + +### **Python Script Requirements** + +```python +# All Python tools must follow these standards + +""" +Module: tool_name.py +Description: [Clear description of what this tool does] +Usage: python tool_name.py [arguments] +""" + +from typing import Optional, List, Dict +import sys +import json + +def main(arg1: str, arg2: Optional[str] = None) -> int: + """ + Main function description. + + Args: + arg1: Description of argument 1 + arg2: Description of optional argument 2 + + Returns: + Exit code (0 for success, 1 for error) + """ + try: + # Tool implementation + result = process_data(arg1, arg2) + + # Output results + if json_output: + print(json.dumps(result, indent=2)) + else: + print(format_human_readable(result)) + + return 0 + except Exception as e: + print(f"Error: {e}", file=sys.stderr) + return 1 + +if __name__ == "__main__": + sys.exit(main()) +``` + +### **Python Quality Checklist** + +```yaml +python_tool_quality: + code_standards: + - [ ] PEP 8 compliant (use pylint or flake8) + - [ ] Type hints for all functions + - [ ] Docstrings for all public functions + - [ ] Clear error messages + - [ ] Proper exception handling + + functionality: + - [ ] Handles missing arguments gracefully + - [ ] Provides helpful usage information (--help) + - [ ] Supports both JSON and human-readable output + - [ ] Returns appropriate exit codes + - [ ] No hardcoded file paths (use relative or arguments) + + dependencies: + - [ ] Uses standard library when possible + - [ ] External dependencies documented in skill README + - [ ] Requirements.txt provided if external packages needed + - [ ] Version constraints specified for dependencies +``` + +## Documentation Quality Standards + +### **Markdown Documentation Requirements** + +```yaml +documentation_quality: + structure: + - [ ] Clear hierarchy with proper headings + - [ ] Table of contents for long documents + - [ ] Consistent formatting throughout + - [ ] Code blocks use appropriate syntax highlighting + - [ ] Lists properly formatted + + content: + - [ ] All links work (no 404s) + - [ ] All code examples tested and working + - [ ] All file paths are correct + - [ ] Screenshots/diagrams up to date + - [ ] No outdated information + + accessibility: + - [ ] Alt text for images + - [ ] Descriptive link text (not "click here") + - [ ] Proper heading hierarchy (no skipping levels) + - [ ] Code examples include explanatory text + + maintenance: + - [ ] Date updated timestamp + - [ ] Version information if applicable + - [ ] Changelog for significant updates +``` + +## Quality Validation Commands + +### **Automated Quality Checks** + +```bash +# Markdown linting +yamllint agents/**/*.md standards/**/*.md documentation/**/*.md + +# Python syntax validation +python -m compileall marketing-skill product-team c-level-advisor engineering-team ra-qm-team + +# Check for broken links (manual check required) +# Verify all ../../ relative paths resolve + +# Test Python tools +for script in $(find . -name "*.py" -path "*/scripts/*"); do + echo "Testing: $script" + python "$script" --help || echo "❌ Failed: $script" +done +``` + +### **Manual Validation Checklist** + +```yaml +pre_commit_validation: + agent_files: + - [ ] YAML frontmatter valid + - [ ] All workflows documented + - [ ] Integration examples present + - [ ] No broken links + - [ ] Relative paths verified + + python_tools: + - [ ] Scripts execute without errors + - [ ] --help flag works + - [ ] Error handling tested + - [ ] Output formats correct + + documentation: + - [ ] README updated if needed + - [ ] CLAUDE.md reflects changes + - [ ] All examples tested + - [ ] Changelog updated + +pre_push_validation: + - [ ] All quality checks pass + - [ ] No secrets in code + - [ ] Commit messages follow convention + - [ ] Branch protection requirements met +``` + +## Quality Metrics for Agents & Skills + +### **Success Criteria** + +```yaml +agent_effectiveness: + workflow_clarity: + target: "Users can follow workflows without assistance" + measurement: "Documentation completeness and clarity" + + tool_reliability: + target: "100% of Python tools execute successfully" + measurement: "Script execution success rate" + + path_resolution: + target: "100% of relative paths resolve correctly" + measurement: "Path validation tests passing" + + integration_quality: + target: "Agents seamlessly invoke skills" + measurement: "Agent-skill integration tests passing" + +documentation_quality: + completeness: + target: "All required sections present" + measurement: "Documentation structure checklist" + + accuracy: + target: "Zero broken links or outdated information" + measurement: "Link validation and content review" + + usability: + target: "Users can implement workflows in <30 minutes" + measurement: "Time-to-implementation tracking" +``` + +## Quality Improvement Process + +### **Continuous Quality Enhancement** + +- **Pre-commit:** Validate syntax, check paths, test tools locally +- **Pull Request:** Peer review, automated testing, quality gate checks +- **Post-merge:** Monitor for issues, collect user feedback +- **Monthly:** Review quality metrics, update standards as needed +- **Quarterly:** Assess skill/agent effectiveness, plan improvements + +### **Quality Issue Resolution** + +```yaml +issue_priority: + P0_critical: + - Broken Python tools (execution failures) + - Invalid relative paths (404 errors) + - Security vulnerabilities + - Data loss or corruption + response_time: "<1 hour" + + P1_high: + - Broken workflows in agents + - Documentation inaccuracies + - Missing required sections + - Performance issues + response_time: "<24 hours" + + P2_medium: + - Enhancement requests + - Documentation improvements + - Code refactoring + - Optimization opportunities + response_time: "<1 week" + + P3_low: + - Nice-to-have features + - Minor documentation updates + - Style improvements + response_time: "<1 month" +``` + +--- + +**Focus**: Python tool quality, agent workflow clarity, skill integration testing +**Updated**: November 2025 +**Review**: Monthly quality assessment +**Compliance**: PEP 8, Markdown standards, relative path conventions diff --git a/standards/security/.gitkeep b/standards/security/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/standards/security/security-standards.md b/standards/security/security-standards.md new file mode 100644 index 0000000..1c65847 --- /dev/null +++ b/standards/security/security-standards.md @@ -0,0 +1,503 @@ +# Security Standards + +## Core Security Principles + +### **1. No Secrets in Code** +- Never hardcode API keys, passwords, or tokens +- Use environment variables for sensitive data +- Exclude sensitive files from git (.env, credentials.json) +- Scan for secrets before committing + +### **2. Dependency Security** +- Use standard library when possible +- Minimize external dependencies +- Keep dependencies updated +- Audit dependencies for vulnerabilities + +### **3. Input Validation** +- Validate all user input +- Sanitize file paths +- Prevent command injection +- Handle edge cases safely + +### **4. Data Protection** +- Don't store sensitive user data +- Encrypt data in transit +- Follow privacy best practices +- Comply with GDPR/CCPA when applicable + +## Secret Detection + +### **Pre-Commit Secret Scanning** + +```bash +# Check for common secrets before committing +git diff --cached | grep -iE 'api[_-]?key|secret|password|token|Bearer|Authorization' + +# Specific patterns to detect +patterns=( + "api[_-]?key.*=.*['\"][^x']+" + "secret.*=.*['\"][^x']+" + "password.*=.*['\"][^x']+" + "token.*=.*['\"][^x']+" + "Bearer\s+[A-Za-z0-9\-._~+/]+" + "sk-[A-Za-z0-9]{20,}" # OpenAI API keys + "ghp_[A-Za-z0-9]{36}" # GitHub Personal Access Tokens + "AKIA[A-Z0-9]{16}" # AWS Access Keys +) +``` + +### **Prohibited Patterns** + +```python +# ❌ Bad - Hardcoded secret +API_KEY = "sk-1234567890abcdef" +password = "mypassword123" + +# ✅ Good - Environment variable +import os +API_KEY = os.getenv("API_KEY") +if not API_KEY: + raise ValueError("API_KEY environment variable not set") +``` + +### **Git Ignore Patterns** + +```gitignore +# Secrets and credentials +.env +.env.* +*.key +*.pem +credentials.json +secrets.yaml +config/local.py + +# Python cache (may contain sensitive data) +__pycache__/ +*.pyc +*.pyo + +# OS files +.DS_Store +Thumbs.db + +# IDE files +.vscode/settings.json +.idea/ +``` + +## Python Security Best Practices + +### **1. Safe File Handling** + +```python +# ✅ Good - Safe path handling +import os +from pathlib import Path + +def read_user_file(filename: str) -> str: + """Safely read user-provided file.""" + # Validate filename + if not filename or '..' in filename or filename.startswith('/'): + raise ValueError("Invalid filename") + + # Use Path for safe path manipulation + base_dir = Path(__file__).parent + file_path = (base_dir / filename).resolve() + + # Ensure file is within allowed directory + if not file_path.is_relative_to(base_dir): + raise ValueError("File path outside allowed directory") + + # Read safely + with open(file_path, 'r') as f: + return f.read() + +# ❌ Bad - Unsafe path handling +def read_file_unsafe(filename: str) -> str: + # Vulnerable to directory traversal + with open(filename, 'r') as f: + return f.read() +``` + +### **2. Command Execution Safety** + +```python +# ✅ Good - Safe command execution +import subprocess +from typing import List + +def run_safe_command(args: List[str]) -> str: + """Execute command safely with argument list.""" + # Use argument list, not shell=True + result = subprocess.run( + args, + capture_output=True, + text=True, + check=True, + timeout=30 # Prevent hanging + ) + return result.stdout + +# Example +output = run_safe_command(['python', 'script.py', '--input', 'file.txt']) + +# ❌ Bad - Shell injection vulnerability +def run_command_unsafe(command: str) -> str: + # Vulnerable to command injection + result = subprocess.run( + command, + shell=True, # DANGEROUS! + capture_output=True + ) + return result.stdout.decode() +``` + +### **3. Input Validation** + +```python +# ✅ Good - Validate and sanitize input +def validate_email(email: str) -> bool: + """Validate email format.""" + import re + pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + return re.match(pattern, email) is not None + +def sanitize_filename(filename: str) -> str: + """Remove unsafe characters from filename.""" + import re + # Remove path separators and null bytes + safe = re.sub(r'[/\\:\0]', '', filename) + # Remove leading dots (hidden files) + safe = safe.lstrip('.') + # Limit length + return safe[:255] + +# ❌ Bad - No validation +def process_input_unsafe(user_input: str): + # Directly using unvalidated input + exec(user_input) # EXTREMELY DANGEROUS! +``` + +### **4. Error Handling** + +```python +# ✅ Good - Don't expose sensitive info in errors +def connect_to_api(api_key: str): + try: + # Connection logic + pass + except Exception as e: + # Don't log the API key! + print("API connection failed. Check your credentials.") + raise ValueError("Authentication failed") from None + +# ❌ Bad - Exposing secrets in error messages +def connect_unsafe(api_key: str): + try: + pass + except Exception as e: + # Leaks API key in logs! + print(f"Failed to connect with key: {api_key}") + raise +``` + +## Dependency Management + +### **Dependency Security Checklist** + +```yaml +dependency_security: + minimize_dependencies: + - [ ] Use Python standard library when possible + - [ ] Justify each external dependency + - [ ] Prefer well-maintained packages + - [ ] Check package reputation (downloads, stars, maintenance) + + version_pinning: + - [ ] Pin exact versions in requirements.txt + - [ ] Use version constraints (>=, <) + - [ ] Document why specific versions required + - [ ] Test upgrades before deploying + + vulnerability_scanning: + - [ ] Run `pip-audit` or `safety check` regularly + - [ ] Review security advisories + - [ ] Update vulnerable packages promptly + - [ ] Monitor dependabot alerts (GitHub) + + license_compliance: + - [ ] Check package licenses + - [ ] Avoid GPL in commercial code (if applicable) + - [ ] Document all licenses + - [ ] Comply with attribution requirements +``` + +### **Security Scanning Commands** + +```bash +# Check for known vulnerabilities in dependencies +pip install pip-audit +pip-audit + +# Or use safety +pip install safety +safety check + +# Check for outdated packages +pip list --outdated + +# Generate requirements with version pins +pip freeze > requirements.txt +``` + +### **Safe Requirements.txt** + +```txt +# Pin exact versions for reproducibility +requests==2.31.0 +pyyaml==6.0.1 + +# Use version constraints for flexibility +click>=8.0.0,<9.0.0 +python-dateutil>=2.8.0 + +# Document why specific versions +# numpy==1.24.0 # Required for Python 3.11 compatibility +``` + +## Data Protection + +### **1. User Data Handling** + +```python +# ✅ Good - Minimal data collection +def analyze_text(text: str) -> dict: + """Analyze text without storing it.""" + # Process locally, don't send to external services + score = calculate_score(text) + return {"score": score} + +# ❌ Bad - Unnecessary data storage +def analyze_text_unsafe(text: str, user_id: str) -> dict: + # Stores user data unnecessarily + save_to_database(user_id, text) + return analyze(text) +``` + +### **2. Privacy Best Practices** + +```yaml +privacy_guidelines: + data_minimization: + - Collect only essential data + - Process data locally when possible + - Delete data after processing + - Don't log sensitive information + + transparency: + - Document what data is collected + - Explain how data is used + - Provide opt-out mechanisms + - Allow data export/deletion + + compliance: + - Follow GDPR if EU users + - Follow CCPA if California users + - Obtain consent for data collection + - Provide privacy policy +``` + +## Code Review Security Checklist + +### **Pre-Commit Security Review** + +```yaml +security_review: + secrets_and_credentials: + - [ ] No hardcoded API keys + - [ ] No hardcoded passwords + - [ ] No hardcoded tokens + - [ ] No private keys committed + - [ ] .env files in .gitignore + + input_validation: + - [ ] All user input validated + - [ ] File paths sanitized + - [ ] SQL queries parameterized (if applicable) + - [ ] Command injection prevented + - [ ] XSS prevention (if web app) + + dependency_security: + - [ ] No known vulnerable dependencies + - [ ] Dependencies minimized + - [ ] Versions pinned in requirements.txt + - [ ] Licenses checked and compatible + + error_handling: + - [ ] Errors don't expose sensitive data + - [ ] Stack traces sanitized in production + - [ ] Logging doesn't include secrets + - [ ] Error messages are user-friendly + + data_protection: + - [ ] Sensitive data not logged + - [ ] Personal data handled properly + - [ ] Encryption used where needed + - [ ] Privacy policy updated (if applicable) +``` + +## Incident Response + +### **Security Issue Severity** + +```yaml +severity_levels: + P0_critical: + description: "Exposed secrets, active exploits, data breach" + response_time: "<1 hour" + actions: + - Rotate exposed credentials immediately + - Disable compromised accounts + - Notify affected users + - Patch vulnerability + - Document incident + + P1_high: + description: "Vulnerable dependencies, potential exploits" + response_time: "<24 hours" + actions: + - Update vulnerable packages + - Test fixes thoroughly + - Deploy security patches + - Monitor for exploitation + + P2_medium: + description: "Security best practice violations" + response_time: "<1 week" + actions: + - Review and fix issues + - Update security documentation + - Educate team + + P3_low: + description: "Minor security improvements" + response_time: "<1 month" + actions: + - Schedule fixes in backlog + - Update standards +``` + +### **Exposed Secret Response** + +```bash +# If you accidentally commit a secret: + +# 1. IMMEDIATELY rotate the credential +# (Change password, regenerate API key, etc.) + +# 2. Remove from git history +git filter-branch --force --index-filter \ + "git rm --cached --ignore-unmatch path/to/file" \ + --prune-empty --tag-name-filter cat -- --all + +# 3. Force push (only if not on main/production!) +git push origin --force --all + +# 4. Notify security team +# Document the incident +``` + +## Security Tools + +### **Recommended Security Tools** + +```yaml +security_tools: + secret_detection: + - gitleaks: "Scan git repos for secrets" + - trufflehog: "Find secrets in git history" + - detect-secrets: "Prevent new secrets" + + dependency_scanning: + - pip-audit: "Scan Python dependencies" + - safety: "Check for known vulnerabilities" + - dependabot: "Automated dependency updates (GitHub)" + + code_analysis: + - bandit: "Python security linter" + - pylint: "General Python linter with security checks" + - semgrep: "Static analysis for security patterns" + + runtime_protection: + - fail2ban: "Prevent brute force attacks (if applicable)" + - rate limiting: "Prevent abuse" + - monitoring: "Detect anomalous behavior" +``` + +### **Security Scanning Script** + +```bash +#!/bin/bash +# security-scan.sh - Run all security checks + +echo "🔒 Running security scans..." + +# Secret detection +echo "Scanning for secrets..." +gitleaks detect --verbose --redact || echo "⚠️ Potential secrets found" + +# Dependency vulnerabilities +echo "Checking dependencies..." +pip-audit || echo "⚠️ Vulnerable dependencies found" + +# Python security linter +echo "Running Bandit security linter..." +bandit -r . -f screen || echo "⚠️ Security issues found" + +# Check for common security issues +echo "Checking for hardcoded secrets..." +grep -r "password\s*=" --include="*.py" . && echo "⚠️ Potential hardcoded passwords" + +echo "✅ Security scan complete" +``` + +## Security Update Process + +### **Regular Security Maintenance** + +- **Weekly:** Review dependabot alerts, scan for secrets +- **Monthly:** Run full security audit, update dependencies +- **Quarterly:** Review security standards, update tools +- **Annually:** Comprehensive security assessment + +### **Security Documentation** + +```markdown +## Security Policy + +### Reporting Security Issues + +**Do NOT open public issues for security vulnerabilities!** + +Email: security@example.com +PGP Key: [link to public key] + +Expected response time: 24 hours + +### Disclosure Process + +1. Report received and acknowledged +2. Issue verified and assessed +3. Fix developed and tested +4. Security advisory published +5. Credits given to reporter +``` + +--- + +**Focus**: Python security, secret detection, dependency management +**Updated**: November 2025 +**Review**: Monthly security assessment +**Compliance**: OWASP Top 10, Python security best practices diff --git a/templates/.gitkeep b/templates/.gitkeep new file mode 100644 index 0000000..e69de29