## 1. Project Overview & Quickstart (Jeffallan/claude-skills) ## File: docs/ideas/audit-primary-docs.md # Documentation Audit: Primary User-Facing Files > Audit date: 2026-02-02 > Auditor: Technical writing agent (Claude Opus 4.5) > Scope: README.md, SKILLS_GUIDE.md, QUICKSTART.md, CONTRIBUTING.md > Supporting context: docs/COMMON_GROUND.md, docs/WORKFLOW_COMMANDS.md, CHANGELOG.md, docs/ideas/documentation-site.md --- ## Executive Summary The four primary documents serve different audiences but suffer from significant content overlap, inconsistent naming conventions, and a structural problem: README.md tries to be both a landing page and a comprehensive reference. SKILLS_GUIDE.md is the strongest standalone document. QUICKSTART.md and CONTRIBUTING.md both contain stale installation instructions that diverge from the README. The biggest single improvement would be thinning the README to a focused landing page and letting specialized documents own their respective topics. --- ## Per-File Findings ### 1. README.md **Purpose:** Project landing page and primary discovery surface (GitHub, search engines, LLM retrieval). **Strengths:** - Strong visual presentation with badges, animated header, star history - Clear "Quick Start" section at the top with copy-paste install command - Well-structured project tree showing directory layout - Good use of the Documentation section as a hub linking to specialized docs - Tech Stack Coverage section serves as an effective keyword surface for search/discovery **Weaknesses:** 1. **Tries to be everything.** At 438 lines, the README functions as landing page, architecture guide, skills catalog, installation manual, usage tutorial, contributing guide, and marketing page. No single audience can scan it efficiently. A first-time visitor looking for "how do I install this" must scroll past architecture diagrams and 65-skill category lists. 2. **Duplicate installation instructions.** Three installation options appear in the "Quick Start" section at the top AND again in "Installation Options" at line 305. These two sections use different option numbering (the Installation Options section has two entries both labeled "Option 2"), different ordering, and different levels of detail. 3. **Skills Overview duplicates SKILLS_GUIDE.md.** Lines 116-133 reproduce a condensed version of the skill catalog that also lives in SKILLS_GUIDE.md. When skills are added or recategorized, both must be updated. Neither is clearly the source of truth. 4. **Context Engineering section duplicates docs/COMMON_GROUND.md.** Lines 182-227 reproduce the overview, command examples, confidence tiers, and mermaid graph that all exist in greater detail in docs/COMMON_GROUND.md. This section is 45 lines of content that could be 5 lines and a link. 5. **Project Workflow Commands section duplicates docs/WORKFLOW_COMMANDS.md.** Lines 229-242 duplicate the phase table from the workflow docs. The README should link, not reproduce. 6. **Contributing section duplicates CONTRIBUTING.md.** Lines 362-401 contain a condensed "Adding a New Skill" guide that partially overlaps with CONTRIBUTING.md but uses different line-count guidance (200-400 lines per reference here vs. no specific range in CONTRIBUTING.md). The frontmatter example in the README uses `name: My Skill` (with spaces), while CONTRIBUTING.md uses a different description formula. CLAUDE.md says names must be "letters, numbers, and hyphens only." 7. **Stale option numbering.** Under "Installation Options," there are two sections both labeled "Option 2" (npx add-skill and Local Development). Option 3 (Direct Installation) should logically be Option 4, or the npx method should be Option 2 and Local Development should be Option 3. 8. **Tech Stack Coverage is a wall of text.** Lines 244-297 list every supported technology in a flat bullet list. This is useful for SEO keyword density on GitHub but provides no navigational value. A reader cannot determine which skill covers which technology from this list alone. **Recommendations:** - Thin the README to under 200 lines: hero, one-line description, single install command, 3-sentence "what is this," link hub to specialized docs, contributing CTA, license/support - Move architecture details to a dedicated `docs/ARCHITECTURE.md` or let the future docs site own it - Remove the inline skills catalog; replace with a single sentence and link to SKILLS_GUIDE.md - Remove the inline Context Engineering section; replace with a 2-line summary and link to docs/COMMON_GROUND.md - Remove the inline Workflow Commands section; link to docs/WORKFLOW_COMMANDS.md - Remove the inline Contributing guide; link to CONTRIBUTING.md - Fix the duplicate "Option 2" numbering immediately (this is a bug regardless of restructuring) - Consider moving Tech Stack Coverage to SKILLS_GUIDE.md where it provides navigational context --- ### 2. SKILLS_GUIDE.md **Purpose:** Quick reference for which skill to use when. **Strengths:** - Clear, scannable structure with consistent formatting throughout - Decision trees are genuinely useful -- they answer the question "I have X problem, which skill do I use?" - Skill Combinations section provides practical multi-skill workflow patterns - Examples section with "Good Prompts" gives concrete, actionable guidance - No unnecessary preamble; gets straight to content - The flattest, most reference-like document in the set -- appropriate for its purpose **Weaknesses:** 1. **No introduction or context.** The document opens with `## When to Use Each Skill` with no preamble explaining what this document is, who it is for, or how it relates to the rest of the project. A single paragraph at the top would help. 2. **Category counts diverge from README.** The README lists 12 categories; SKILLS_GUIDE.md lists 12 categories but with different groupings. For example, README has "Workflow (2): Debugging Wizard, Fullstack Guardian" as a category, while SKILLS_GUIDE.md has the same skills under a "Workflow" heading. This is consistent, but the README's parenthetical counts (e.g., "Languages (12)") are not replicated here, making cross-reference verification manual. 3. **Examples section is excessively long.** Lines 257-322 contain 50+ example prompts across 7 subsections. This is valuable content, but the sheer volume makes it hard to scan. The most common use cases (top 10) should be separated from the exhaustive list. 4. **No link back to README or installation.** A reader who lands here directly (via search, deep link, or LLM referral) has no way to learn how to install the plugin. A single line at the top with a link to the README or QUICKSTART.md would solve this. 5. **"Tips for Effective Use" is generic.** The 5 tips at line 249-255 are so general ("Be Specific," "Context Matters") that they add little value. They duplicate the more concrete best practices in QUICKSTART.md. 6. **Missing: which skills are new or recently updated.** For returning users, a "What's New" callout at the top referencing the latest release would help. **Recommendations:** - Add a 2-3 line introduction with a link to README.md and QUICKSTART.md - Trim the Examples section: keep the top 16 "Good Prompts" and move the framework-specific, language-specific, and platform-specific examples into a collapsible section or separate file - Remove or merge "Tips for Effective Use" into QUICKSTART.md where it belongs - Consider adding a "Last updated: vX.Y.Z" line at the top so readers know if content is current --- ### 3. QUICKSTART.md **Purpose:** Get a new user from zero to working installation in minutes. **Strengths:** - Starts with installation immediately -- no preamble - Three installation methods presented concisely - "Test Your Installation" section is a strong inclusion -- gives the user a way to verify success - "Quick Reference Card" at the bottom is a genuinely useful cheat sheet - Reasonable length (208 lines) **Weaknesses:** 1. **Installation instructions diverge from README.** QUICKSTART.md offers three methods: Marketplace, Install from GitHub (`claude plugin install https://...`), and Local Development (`cp -r`). README.md offers four methods: Marketplace, npx add-skill, Local Development, and Direct Installation. The "Install from GitHub" method in QUICKSTART.md (`claude plugin install https://...`) does not appear in the README at all. The npx method in the README does not appear in QUICKSTART.md. This is confusing and suggests neither document is the source of truth. 2. **Skill counts may go stale.** Lines 50-54 contain hardcoded counts ("12 Language Experts," "10 Backend Framework Experts," "7 Frontend & Mobile Experts"). These are not wrapped in `` markers and will not be updated by `scripts/update-docs.py`. The "10 Backend Framework Experts" claim conflicts with the README, which lists 7 in the "Backend Frameworks" category. 3. **"First Steps" section mixes audiences.** Subsections 1-4 cover what the plugin contains (reference), common use cases (tutorial), best practices (guidance), and skill activation examples (reference). This interleaving makes it hard to follow a linear getting-started path. 4. **"Follow Recommended Workflows" duplicates SKILLS_GUIDE.md.** The 7-step new feature workflow at lines 127-134 is identical to the "New Feature Development" workflow in SKILLS_GUIDE.md lines 96-104. One should link to the other. 5. **References section at line 136-139 is incomplete.** It lists README.md, SKILLS_GUIDE.md, and CONTRIBUTING.md, but omits docs/COMMON_GROUND.md and docs/WORKFLOW_COMMANDS.md. 6. **Troubleshooting is thin.** Only two scenarios are covered (skills not activating, need help). Common issues like "I installed but Claude does not seem to use the skills" or "how do I update to the latest version" are not addressed. 7. **Closing tone is informal.** "Happy coding!" with a rocket emoji is not consistent with the professional tone of the rest of the documentation set. **Recommendations:** - Consolidate installation instructions with the README. One document should be the canonical source; the other should link to it. Recommendation: QUICKSTART.md owns the detailed install instructions; README.md has a one-liner and a link. - Fix the stale "10 Backend Framework Experts" count (should be 7 per README categories, or 8 if counting Express separately) - Restructure "First Steps" into a linear flow: Install -> Verify -> Try your first prompt -> Learn more - Remove the duplicated workflow; link to SKILLS_GUIDE.md - Expand the Troubleshooting section with 2-3 more common scenarios - Add "How to update" instructions - Remove the closing emoji; end with the Support section --- ### 4. CONTRIBUTING.md **Purpose:** Guide contributors through the process of adding or modifying skills. **Strengths:** - Clear step-by-step contribution workflow (fork, branch, change, test, commit, PR) - Commit message format is well-defined - Progressive Disclosure Pattern section is thorough and well-explained - Token Efficiency Guidelines are specific and actionable - Code Examples Best Practices section sets a clear standard - Framework Version Requirements table pins versions -- good for consistency **Weaknesses:** 1. **Frontmatter schema conflicts with CLAUDE.md.** CONTRIBUTING.md line 88 shows `name: Skill Name` (with a space), but CLAUDE.md explicitly states: "name: Letters, numbers, and hyphens only (no parentheses or special characters)." The description formula on line 103 (`[Role] for [Domain]. Invoke for [triggers]. Keywords: [terms].`) conflicts with CLAUDE.md's mandate: "descriptions must be TRIGGER-ONLY" and "Format: `Use when [specific triggering conditions]`." These are not minor style differences; they will produce skills that fail validation. 2. **Missing validation step.** The contribution workflow (steps 1-6) does not mention running `python scripts/validate-skills.py` before submitting a PR. Given that CI runs this check, contributors will hit failures they could have caught locally. This should be step 4.5. 3. **Reference file guidance is vague.** The README says "200-400 lines each" for references. CLAUDE.md says "100-600 lines per reference file." CONTRIBUTING.md's Progressive Disclosure section says "200 lines" as a threshold for when to split, but does not state a target range. Three different documents give three different numbers. 4. **Testing instructions are impractical.** Step 4 says to `cp -r skills/* ~/.claude/skills/` and restart Claude Code. For marketplace-installed plugins, this method may not work or may conflict with the installed version. No guidance is given for testing with the marketplace/local plugin workflow. 5. **No mention of the `commands/` directory.** The guide covers skill creation in detail but says nothing about creating or modifying workflow commands. A contributor looking to add a command has no guidance. 6. **Code of Conduct is minimal.** Three short subsections (Be Respectful, Be Collaborative, Be Professional) with two bullet points each. This is fine for a small project but may need expansion as community grows. Consider linking to a standard CoC (e.g., Contributor Covenant) instead of maintaining a custom one. 7. **"Recognition" section references a CONTRIBUTORS.md file.** This file does not appear in the project structure shown in README.md. If it exists, it should be linked. If it does not exist, this is a broken promise. **Recommendations:** - Align the frontmatter schema with CLAUDE.md immediately. The description formula must say "Use when [triggering conditions]," not the `[Role] for [Domain]` pattern. The name field must show a hyphenated example. - Add `python scripts/validate-skills.py --skill my-new-skill` as an explicit step before submitting a PR - Standardize reference file line guidance across all documents (CLAUDE.md's 100-600 range is the most permissive; pick one range and use it everywhere) - Add a section on contributing workflow commands - Link or create the CONTRIBUTORS.md file - Add a note about testing with the marketplace install method --- ## Cross-File Redundancy Map The following content appears in multiple documents. For each topic, one document should be the **single source of truth (SSoT)**; all others should link to it. | Topic | README | QUICKSTART | SKILLS_GUIDE | CONTRIBUTING | Recommended SSoT | |-------|--------|------------|--------------|--------------|-------------------| | Installation methods | 4 methods (lines 306-347) | 3 methods (lines 8-27) | -- | 1 method (line 51) | QUICKSTART.md | | Skill category list | Lines 120-132 | Lines 50-55 | Lines 5-93 | -- | SKILLS_GUIDE.md | | New feature workflow | Lines 167-169 | Lines 127-134 | Lines 96-104 | -- | SKILLS_GUIDE.md | | Bug fixing workflow | Lines 172-174 | -- | Lines 107-111 | -- | SKILLS_GUIDE.md | | Context Engineering overview | Lines 182-227 | -- | -- | -- | docs/COMMON_GROUND.md | | Workflow Commands table | Lines 233-238 | -- | -- | -- | docs/WORKFLOW_COMMANDS.md | | Skill activation examples | Lines 139-161 | Lines 99-108 | Lines 259-322 | -- | SKILLS_GUIDE.md | | Best practices / tips | Lines 136-161 | Lines 85-95, 110-134 | Lines 249-255 | -- | QUICKSTART.md | | Progressive disclosure explanation | Lines 46-73 | -- | -- | Lines 172-226 | CONTRIBUTING.md | | Contributing quick guide | Lines 362-401 | -- | -- | Full document | CONTRIBUTING.md | | Frontmatter schema | Lines 373-387 | -- | -- | Lines 84-98 | CONTRIBUTING.md | | Tech stack coverage | Lines 244-297 | Lines 176-198 (condensed) | Implicit in categories | -- | SKILLS_GUIDE.md (integrated into categories) | | Support links | Lines 413-415 | Lines 200-205 | -- | Lines 296-298 | README.md | | Project structure tree | Lines 74-108 | -- | -- | Lines 177-184 (partial) | README.md | **Key finding:** 14 topics are duplicated across 2 or more files. Installation instructions appear in 3 files with different content in each. The skill activation examples appear in 3 files with varying levels of detail. --- ## Proposed Restructuring for a Docs Site This mapping assumes the docs site structure proposed in `docs/ideas/documentation-site.md` and assigns each piece of current content to its future home. Retain only: - Hero banner and badges - 3-sentence project description - Single install command with link to full QUICKSTART.md - Link hub: Quick Start, Skills Guide, Common Ground, Workflow Commands, Contributing - License, Support, Author - Star history / social proof Everything else moves to dedicated pages. ### /getting-started/ (from QUICKSTART.md) - All installation methods (single source of truth) - Verification steps - First prompt walkthrough - Troubleshooting - How to update ### /skills/ (from SKILLS_GUIDE.md) - Skill index (filterable) - Decision trees - Skill combinations - Example prompts (condensed) - Tech stack coverage (integrated into skill cards) ### /architecture/ (from README.md sections) - Progressive disclosure pattern explanation - Project structure tree - How skills activate (context-aware activation) ### /workflows/ (from docs/WORKFLOW_COMMANDS.md) - Phase overview with DAG diagram - Command reference table - Per-command detail pages ### /common-ground/ (from docs/COMMON_GROUND.md) - Existing content, mostly unchanged - Remove background/origin story from main flow; move to a "Design Philosophy" subpage ### /contributing/ (from CONTRIBUTING.md) - Fork/branch/test/PR workflow - Skill writing guidelines (single source of truth for frontmatter schema) - Reference file standards - Validation and testing - Add: command writing guidelines --- ## Priority Ranking of Improvements ### Critical (Fix Now) 1. **Fix duplicate "Option 2" numbering in README.md Installation Options.** This is a visible bug. 2. **Align CONTRIBUTING.md frontmatter schema with CLAUDE.md.** The description formula and name format directly conflict with the project's own CLAUDE.md. Contributors following CONTRIBUTING.md will produce skills that fail validation. Change the description formula to `Use when [triggering conditions]` and the name example to `my-skill-name` (hyphenated). 3. **Fix stale count "10 Backend Framework Experts" in QUICKSTART.md.** This contradicts the README (which says 7). Either wrap these counts in update markers or replace with a general statement. ### High Priority (Next Release) 4. **Consolidate installation instructions.** Designate QUICKSTART.md as the single source of truth. README.md gets a one-liner and a link. CONTRIBUTING.md links to QUICKSTART.md for testing setup. Remove the `claude plugin install https://...` method from QUICKSTART.md if it is not a supported path, or add it to the README if it is. 5. **Remove duplicated sections from README.md.** Replace inline Context Engineering, Workflow Commands, Skills Overview, and Contributing sections with 2-line summaries and links. Target: README under 200 lines. 6. **Add `validate-skills.py` step to CONTRIBUTING.md.** Insert between "Test Your Changes" and "Commit Your Changes." 7. **Standardize reference file line guidance.** Pick one range (recommend 100-600 from CLAUDE.md) and use it in README.md, CONTRIBUTING.md, and CLAUDE.md consistently. ### Medium Priority (Docs Site Prep) 8. **Add introduction and navigation links to SKILLS_GUIDE.md.** A 3-line preamble with links to README and QUICKSTART. 9. **Trim SKILLS_GUIDE.md examples section.** Keep top 16 general examples; move framework-specific and platform-specific examples to a separate section or file. 10. **Expand QUICKSTART.md troubleshooting.** Add "how to update," "skills conflict with local files," and "which installation method should I choose." 11. **Add workflow command contribution guidance to CONTRIBUTING.md.** 12. **Restructure QUICKSTART.md "First Steps" into a linear tutorial flow.** ### Nice-to-Have (Future) 13. **Add "Last updated" or version reference to SKILLS_GUIDE.md and QUICKSTART.md.** 14. **Create or link CONTRIBUTORS.md** referenced in CONTRIBUTING.md Recognition section. 15. **Replace minimal Code of Conduct with Contributor Covenant link.** 16. **Move Tech Stack Coverage from README to SKILLS_GUIDE.md** where it provides navigational context next to the decision trees. 17. **Remove "Tips for Effective Use" from SKILLS_GUIDE.md** (merge into QUICKSTART.md best practices). 18. **Standardize tone across all documents.** QUICKSTART.md ends with "Happy coding!" and uses emoji bullets in the Support section. Other documents maintain a more neutral professional tone. Pick one voice and apply it everywhere. --- ## SEO Readiness Assessment | Criterion | README | QUICKSTART | SKILLS_GUIDE | CONTRIBUTING | |-----------|--------|------------|--------------|--------------| | Descriptive H1 | No (image banner, no text H1) | Yes | Yes | Yes | | Unique page title potential | Yes ("Claude Skills") | Yes ("Quick Start Guide") | Yes ("Skills Quick Reference") | Yes ("Contributing") | | Scannable headings | Mixed (some headings are vague: "Architecture," "Usage Patterns") | Yes | Yes | Yes | | Keyword density | High (tech stack list) | Medium | High (skill names, frameworks) | Low (process-focused) | | Internal linking | Good (links to all major docs) | Weak (3 links) | None | Weak (1 link) | | External linking | Good (GitHub, LinkedIn) | Weak (1 GitHub link) | None | Weak (1 GitHub link) | | Meta description potential | Implicit in first paragraph | Implicit | Missing (no intro paragraph) | Implicit | | Standalone readability | No (assumes GitHub context) | Mostly yes | No (no intro, no install link) | Yes | **Key SEO gaps:** - SKILLS_GUIDE.md has zero internal or external links. On a docs site, it would be an isolated page with no link equity flow. - README.md has no text-based H1. The project name is embedded in an image. Search engines may not extract it. - None of the documents have a meta-description-ready opening sentence that summarizes the page in under 160 characters. --- ## Relationship to docs/ideas/documentation-site.md This audit directly satisfies **Phase 1** of the documentation site plan. The findings here feed into Phase 2 (Content Restructuring). Specifically: - The redundancy map above identifies exactly which content to deduplicate before building the site - The proposed restructuring section provides a content-to-URL mapping for the Astro site structure - The priority ranking ensures the most impactful fixes happen before the site build, reducing rework - The SEO readiness assessment identifies gaps that the docs site should address with proper meta tags, H1 elements, and internal linking **Recommended next step:** Execute Critical and High Priority items (1-7) in the current repo before beginning Phase 4 (Astro setup). These fixes improve the current GitHub-based experience and reduce content migration work. --- ## File: docs/ideas/audit-skill-consistency.md # Skill SKILL.md Consistency Audit Report > Audit date: 2026-02-02 > Audited by: Claude Opus 4.5 > Sample size: 10 skills out of 65 total > Reference standard: CLAUDE.md project instructions (Skill Authorship Standards) --- ## 1. Consistency Matrix The table below tracks whether each sampled skill conforms to the documented standard for each dimension. | Dimension | react-expert | nestjs-expert | python-pro | code-reviewer | architecture-designer | feature-forge | debugging-wizard | terraform-engineer | security-reviewer | pandas-pro | |-----------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | **Frontmatter: required fields** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Description starts "Use when"** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Description trigger-only (no process)** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Description has "Invoke for" clause** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Role: valid enum value** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Scope: valid enum value** | PASS | PASS | PASS | PASS | PASS | PASS | WARN | PASS | PASS | PASS | | **Output-format: valid enum value** | PASS | PASS | PASS | PASS | PASS | PASS | WARN | PASS | PASS | PASS | | **H1 title present** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Role Definition section** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **When to Use section (bullet list)** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | FAIL | PASS | | **Core Workflow (5 steps)** | PASS | PASS | PASS | PASS | PASS | PASS | FAIL (6) | PASS | FAIL (6) | PASS | | **Reference Guide table** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Constraints: MUST DO** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Constraints: MUST NOT DO** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Output Templates section** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Knowledge Reference section** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Related Skills section** | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | PASS | | **Related Skills all valid** | PASS | PASS | FAIL | PASS | PASS | PASS | PASS | FAIL | FAIL | FAIL | | **No extra non-standard sections** | PASS | PASS | PASS | PASS | PASS | FAIL | PASS | PASS | PASS | PASS | | **Line count 80-100** | 78 (low) | 74 (low) | 72 (low) | 72 (low) | 69 (low) | 75 (low) | 73 (low) | 77 (low) | 74 (low) | 76 (low) | | **`allowed-tools` field** | -- | -- | -- | PASS | -- | -- | -- | -- | PASS | -- | **Legend:** PASS = conforms, FAIL = deviates, WARN = uses value outside documented enum but value is reasonable, -- = not applicable --- ## 2. Common Quality Issues Across Skills ### 2.1 Phantom Related Skills References (CRITICAL) The most significant cross-cutting issue. Multiple skills reference Related Skills that **do not exist** in the repository. Across the 10 sampled skills, 4 contain broken references. A broader search reveals this is a systemic problem across the full skill set (30+ phantom references found). **Phantom names found in sampled skills:** | Phantom Reference | Found In | Closest Actual Skill | |---|---|---| | "Data Science Pro" | python-pro | `pandas-pro` | | "Cloud Architect" | terraform-engineer | `cloud-architect` (this one actually exists) | | "Security Engineer" | terraform-engineer | `security-reviewer` or `secure-code-guardian` | | "Secure Code Guardian" (display name) | architecture-designer, security-reviewer | `secure-code-guardian` (exists, but display name differs from H1 title) | | "Data Scientist" | pandas-pro | No equivalent skill | **Broader systemic phantoms found across all skills (not just sample):** - "Backend Developer" (referenced by 6 skills) -- does not exist - "Performance Engineer" (referenced by 8 skills) -- does not exist - "Data Engineer" (referenced by 3 skills) -- does not exist - "TypeScript Expert" (referenced in javascript-pro) -- actual name is `typescript-pro` - "React Developer" (referenced in javascript-pro, typescript-pro) -- actual name is `react-expert` - "Azure Specialist" (referenced in csharp-developer) -- does not exist - "IoT Engineer" (referenced in embedded-systems) -- does not exist - "Cloud Architect" (referenced by 7 skills) -- actually exists as `cloud-architect` - "Security Engineer" (referenced by 2 skills) -- does not exist **Root cause:** Related Skills use human-readable display names (e.g., "Backend Developer") that are not validated against the actual skill inventory. Some are aspirational references to skills that were never created. Others use slightly different display names than the actual skill's H1 title. ### 2.2 All Skills Fall Below Target Line Count CLAUDE.md specifies Tier 1 SKILL.md files should be "~80-100 lines." Every sampled skill falls below the target range: | Skill | Lines (non-blank) | Total Lines | |---|---|---| | react-expert | 78 | ~99 | | nestjs-expert | 74 | ~95 | | python-pro | 72 | ~93 | | code-reviewer | 72 | ~93 | | architecture-designer | 69 | ~90 | | feature-forge | 75 | ~100 | | debugging-wizard | 73 | ~94 | | terraform-engineer | 77 | ~98 | | security-reviewer | 74 | ~95 | | pandas-pro | 76 | ~97 | When blank lines are included, most files are close to the lower end of the 80-100 range. This is acceptable but means there is no headroom -- no skill invests its "line budget" on skill-specific nuances that would differentiate it from a template fill. ### 2.3 Core Workflow Step Count Inconsistency CLAUDE.md specifies "Core workflow (5 high-level steps)." Two sampled skills use 6 steps: - **debugging-wizard**: 6 steps (Reproduce, Isolate, Hypothesize, Test, Fix, Prevent) - **security-reviewer**: 6 steps (Scope, Automated scan, Manual review, Active testing, Categorize, Report) Both 6-step workflows are domain-justified and arguably better for it. This suggests the "5 steps" guidance may be too rigid, or these skills should be brought into compliance. ### 2.4 Frontmatter Enum Drift The CLAUDE.md documents these enums: - `scope`: `implementation | review | design | system-design` - `output-format`: `code | document | report | architecture` **Actual values found across the full 65-skill set that fall outside these enums:** | Field | Non-standard Value | Skill(s) | |---|---|---| | `scope` | `analysis` | debugging-wizard | | `scope` | `testing` | playwright-expert, test-master | | `scope` | `infrastructure` | kubernetes-specialist, cloud-architect | | `scope` | `optimization` | database-optimizer | | `scope` | `architecture` | legacy-modernizer | | `output-format` | `analysis` | debugging-wizard | | `output-format` | `manifests` | kubernetes-specialist | | `output-format` | `specification` | api-designer | | `output-format` | `schema` | graphql-architect | | `output-format` | `analysis-and-code` | database-optimizer | | `output-format` | `code+analysis` | legacy-modernizer | These are all reasonable values. The issue is that CLAUDE.md's enum list is incomplete, not that the skills are wrong. The documented enums need to be expanded, or a note added that custom values are permitted. ### 2.5 Non-Standard Frontmatter Fields Two fields appear in some skills but are not documented in CLAUDE.md's Frontmatter Requirements: - `allowed-tools`: Used by `code-reviewer`, `spec-miner`, `security-reviewer` (3 skills) This field is meaningful (restricts which tools the skill can use) but is undocumented. It should either be added to the frontmatter spec or removed from the skills. ### 2.6 "When to Use" Format Inconsistency 9 of 10 sampled skills use a **bullet list** under "When to Use This Skill." The exception is **security-reviewer**, which uses a comma-separated prose paragraph: ``` Code review, SAST, vulnerability scanning, dependency audits, secrets scanning, penetration testing, reconnaissance, infrastructure/cloud security audits, DevSecOps pipelines, compliance automation. ``` This is the only format deviation in the sample but should be standardized for docs site generation. ### 2.7 Output Templates Format Inconsistency Most skills use a numbered list under "Output Templates." Two deviate: - **security-reviewer**: Uses inline prose with numbered parentheticals: `"Provide: (1) Executive summary... (2) Findings table..."` - **debugging-wizard**: Uses bold labels in a numbered list (a richer format than others) Neither is wrong, but for docs site rendering consistency, a single format should be chosen. ### 2.8 Attribution Comments in Routing Tables Three skills contain HTML comments for attribution in their Reference Guide tables: - `code-reviewer`: `` - `debugging-wizard`: Same pattern - `test-master`: Same pattern These are invisible in rendered markdown but would appear in raw source. For a docs site generator that processes SKILL.md files, these should either be preserved (if attribution is required) or moved to a separate attribution section. --- ## 3. Section Order Analysis The expected section order (derived from CLAUDE.md's Progressive Disclosure Architecture and the majority pattern) is: ``` 1. YAML Frontmatter 2. # Title 3. One-line subtitle/description 4. ## Role Definition 5. ## When to Use This Skill 6. ## Core Workflow 7. ## Reference Guide (table) 8. ## Constraints (### MUST DO, ### MUST NOT DO) 9. ## Output Templates 10. ## Knowledge Reference 11. ## Related Skills ``` **All 10 sampled skills follow this exact order**, with one exception: - **feature-forge** adds a non-standard `## Pre-Discovery with Subagents` section between "Core Workflow" and "Reference Guide." This is the only skill in the sample with an extra section. This is a strong positive finding: section order is highly consistent. --- ## 4. Per-Skill Deviations (Only Where Notable) ### 4.1 feature-forge - **Extra section:** `## Pre-Discovery with Subagents` is a non-standard section not found in other skills. It describes a multi-agent workflow pattern. - **Tool-specific constraints:** References `AskUserQuestions` tool explicitly in both Core Workflow and Constraints. This is unique among sampled skills and raises a question: should skills reference specific tools by name, or keep tool usage implicit? - **File output path:** Specifies `Save as: specs/{feature_name}.spec.md` in Output Templates -- the only skill to prescribe a file path. ### 4.2 security-reviewer - **"When to Use" is prose, not bullets** (see section 2.6 above). - **Core Workflow has 6 steps** instead of 5. - **Output Templates is prose** instead of numbered list. - **Has `allowed-tools` field** not in the documented frontmatter spec. - Overall, this skill deviates more from the template than any other in the sample. ### 4.3 debugging-wizard - **Core Workflow has 6 steps** instead of 5. - **`scope: analysis`** and **`output-format: analysis`** are outside documented enums. - **Output Templates uses bold labels** (e.g., `**Root Cause**:`, `**Evidence**:`) -- richer format than others. ### 4.4 code-reviewer - **Has `allowed-tools` field** (undocumented in spec). - **Attribution HTML comment** in Reference Guide table. ### 4.5 python-pro - **Phantom Related Skill:** References "Data Science Pro" which does not exist. ### 4.6 terraform-engineer - **Phantom Related Skill:** References "Security Engineer" which does not exist. - References "Cloud Architect" which does exist. ### 4.7 pandas-pro - **Phantom Related Skill:** References "Data Scientist" which does not exist. - Only 2 Related Skills listed (fewest in sample; others have 3-4). ### 4.8 architecture-designer - **Lowest line count** in sample (69 non-blank lines). - Related Skills reference names ("Secure Code Guardian") that use different casing/display than the H1 title in the actual skill. ### 4.9 react-expert, nestjs-expert No notable deviations. These are the most template-conformant skills in the sample. --- ## 5. Docs Site Readiness Assessment ### What Works Well for Standalone Pages 1. **Consistent section structure** -- The 11-section order is machine-parseable and could directly map to page sections. 2. **YAML frontmatter** -- Provides structured metadata for page generation (title, category via scope, output type). 3. **Reference Guide table** -- Could generate "See Also" or "Deep Dive" link sections. 4. **Constraints** -- MUST DO / MUST NOT DO sections are visually distinctive and could be rendered as callout boxes. 5. **Related Skills** -- Natural cross-linking between pages (once phantom references are fixed). ### What Is Missing for Standalone Pages | Gap | Impact | Effort | |---|---|---| | **No skill category/domain field** in frontmatter | Cannot auto-generate category pages (Frontend, Backend, etc.) | Low -- add `category` field | | **No version/last-updated field** in frontmatter | Cannot show freshness on docs site | Low -- add `version` or `last-updated` field | | **No short summary** separate from description | Description is trigger-focused; pages need a human-readable 1-2 sentence summary | Medium -- add `summary` field or derive from subtitle | | **Related Skills use display names, not slugs** | Cannot auto-link without a name-to-slug mapping | Medium -- switch to slugs or add mapping | | **Reference Guide paths are relative** | Docs site needs resolvable links | Low -- establish URL convention | | **No difficulty/complexity indicator** | Users cannot self-select skills by experience level | Low -- add to frontmatter | | **One-line subtitle has no consistent format** | Some are "Senior X specializing in Y", some are "Expert X developer..." | Low -- standardize template | | **Knowledge Reference is a comma-separated string** | Not parseable for tag generation | Medium -- convert to YAML list or use triggers for this | --- ## 6. Template Recommendation Based on this audit, the ideal SKILL.md structure for docs site generation would be: ```yaml --- name: skill-name-with-hyphens description: Use when [triggering conditions]. Invoke for [specific keywords]. summary: One-sentence human-readable summary for docs site cards. category: frontend|backend|language|quality|architecture|design|workflow|infrastructure|security|data|devops|testing triggers: [keyword1, keyword2, keyword3] role: specialist|expert|architect scope: implementation|review|design|system-design|analysis|testing|infrastructure|optimization output-format: code|document|report|architecture|analysis|specification version: "1.0" --- # Skill Display Name One-line role statement: "Senior [role] specializing in [domain]." ## Role Definition 2-3 sentences establishing persona, years of experience, and specializations. ## When to Use This Skill - Bullet list only (no prose paragraphs) - 5-7 specific triggering scenarios - Each bullet starts with a gerund (Building, Implementing, etc.) ## Core Workflow 1. **Verb** - Brief description (5 steps, no more, no fewer) 2. **Verb** - Brief description 3. **Verb** - Brief description 4. **Verb** - Brief description 5. **Verb** - Brief description ## Reference Guide Load detailed guidance based on context: | Topic | Reference | Load When | |-------|-----------|-----------| | Topic Name | `references/filename.md` | Specific triggering condition | ## Constraints ### MUST DO - Specific, domain-relevant imperatives (not generic platitudes) - 6-8 items ### MUST NOT DO - Specific, domain-relevant prohibitions - 6-8 items ## Output Templates When implementing [domain] solutions, provide: 1. Numbered list format only 2. 3-5 deliverables 3. Each item is a concrete artifact ## Knowledge Reference Comma-separated list of technologies, standards, and tools. ## Related Skills - **Actual Skill Display Name** - Relationship context (use exact H1 title from target skill) - 3-4 related skills minimum ``` --- ## 7. Priority-Ranked Recommendations ### Critical (Must fix before docs site generation) 1. **Fix all phantom Related Skills references.** Audit every skill's Related Skills against the actual inventory of 65 skills. Either correct the display name to match an existing skill's H1 title, or remove the reference. Estimated: 30+ broken references across the full set. 2. **Standardize Related Skills to use resolvable identifiers.** Currently these use human-friendly display names that cannot be auto-linked. Options: - (a) Use the frontmatter `name` (slug) as a machine-readable identifier alongside the display name - (b) Build a display-name-to-slug mapping table - (c) Add a `display-name` field to frontmatter so the mapping is self-contained 3. **Expand the documented frontmatter enums** in CLAUDE.md to match actual usage. Add `analysis`, `testing`, `infrastructure`, `optimization`, `architecture` to `scope`. Add `analysis`, `manifests`, `specification`, `schema` to `output-format`. ### High (Should fix for quality) 4. **Standardize the "When to Use" section** to always use bullet lists, not prose. Fix security-reviewer. 5. **Standardize the "Output Templates" section** to always use numbered lists, not inline prose. Fix security-reviewer. 6. **Enforce the 5-step Core Workflow rule** or explicitly amend CLAUDE.md to allow 5-6 steps. Two skills (debugging-wizard, security-reviewer) have 6 steps that are domain-justified. 7. **Document the `allowed-tools` frontmatter field** in CLAUDE.md, or decide it belongs in a separate mechanism. 8. **Remove or relocate non-standard sections** (feature-forge's "Pre-Discovery with Subagents") into a reference file to maintain the standard section order. ### Medium (Should fix for docs site polish) 9. **Add a `category` frontmatter field** for docs site navigation. Values like `frontend`, `backend`, `language`, `quality`, `architecture`, `design`, `workflow`, `infrastructure`, `security`, `data`, `devops`, `testing` would enable auto-generated category index pages. 10. **Add a `summary` frontmatter field** (or standardize the subtitle line) for docs site cards and search results. The current `description` is trigger-focused and reads awkwardly as a page summary. 11. **Standardize the subtitle line format** after the H1. Propose template: `"Senior [role] specializing in [1-2 domains] with expertise in [signature capability]."` 12. **Convert Reference Guide relative paths** to a docs-site-resolvable format, or establish a URL convention that a build step can apply. ### Low (Nice to have) 13. **Consider converting Knowledge Reference** from comma-separated prose to a YAML list in frontmatter (or a bullet list in the body) for tag generation on the docs site. 14. **Add `version` or `last-updated` metadata** to frontmatter for docs site freshness indicators. 15. **Standardize Related Skills count** to 3-4 per skill. pandas-pro has only 2; some non-sampled skills have 4-5. 16. **Handle attribution HTML comments** in routing tables. Decide whether to preserve as-is, move to a footer, or add an `attribution` frontmatter field. 17. **Consider adding a `difficulty` or `experience-level` field** to help users self-select appropriate skills. --- ## 8. Validation Script Gaps The existing `scripts/validate-skills.py` checks YAML parsing, required fields, name format, description prefix, references directory, and count consistency. Based on this audit, the following checks should be added: 1. **Related Skills existence check** -- Verify each bold name in Related Skills maps to an actual skill's H1 title or frontmatter name. 2. **Core Workflow step count** -- Warn if not exactly 5 (or 5-6 if the standard is amended). 3. **"When to Use" format check** -- Ensure section uses bullet list format, not prose. 4. **Frontmatter enum validation** -- Check `scope` and `output-format` against the expanded (documented) enum list. 5. **Section order check** -- Verify sections appear in the canonical order. 6. **Line count check** -- Warn if below 80 or above 100 non-blank lines. --- ## 9. Summary The skill set shows strong structural consistency. The 11-section template is followed by all 10 sampled skills, with section order preserved perfectly in 9 of 10 cases. Frontmatter fields are present and well-formed. Descriptions consistently follow the "Use when... Invoke for..." pattern. The critical gap is **phantom Related Skills references** -- a systemic issue affecting approximately half the skill set and blocking reliable cross-linking on a docs site. The secondary gap is **enum drift** in frontmatter values, where actual usage has outgrown the documented specification. Addressing the Critical and High priority items (8 items) would make the skill set docs-site-ready. The Medium and Low items (9 items) would polish the experience but are not blockers. --- ## File: docs/ideas/audit-workflow-docs.md # Workflow Documentation Audit Report > Conducted: 2026-02-02 > Scope: Workflow commands, command docs, guides, YAML definitions, and cross-references > Method: Full read of all files in scope, cross-referencing YAML definitions against docs --- ## Executive Summary The workflow documentation is unusually thorough for a project of this size. The `WORKFLOW_COMMANDS.md` file is a well-structured 876-line reference with mermaid diagrams, input/output tables, and checkpoint documentation. The `docs/workflow/` directory provides a clean separation between phase overviews and per-command descriptions, and the YAML definitions are consistent and well-typed. However, the documentation has grown organically across three layers (README, `WORKFLOW_COMMANDS.md`, and `docs/workflow/`) without clear delineation of audience or purpose. This creates significant redundancy, a confusing entry path for new users, and several structural mismatches between what the YAML definitions declare and what the docs describe. This report documents all findings, organizes them by area, and proposes a restructuring plan for migration to Astro + Starlight. --- ## 1. Per-Area Findings ### 1.1 `docs/WORKFLOW_COMMANDS.md` **Strengths:** - Comprehensive: covers all four phases with mermaid diagrams, command signatures, process steps, output sections, and publish locations. - The Document Flow Summary table (lines 87-97) is an excellent quick-reference artifact. - Checkpoint documentation (lines 740-812) is thorough and includes realistic examples with response types. - Workflow Variations section (lines 816-838) clearly communicates the three main paths through the system. **Weaknesses:** - **Drift from YAML manifest.** The document describes four phases (Discovery, Planning, Execution, Retrospectives) and nine commands. The YAML manifest defines five phases (Intake, Discovery, Planning, Execution, Retrospective) and twelve commands plus one utility. The entire Intake phase (3 commands) is absent from `WORKFLOW_COMMANDS.md`. - **Naming inconsistencies.** The document uses old command names (`create-epic-discovery`, `synthesize-discovery`, `approve-synthesis`, `create-epic-plan`, `create-implementation-plan`) while the YAML manifest uses shorter identifiers (`discovery:create`, `discovery:synthesize`, `discovery:approve`, `planning:epic-plan`, `planning:impl-plan`). A reader switching between the two sources will be confused about which name to use. - **`complete-sprint` is documented but absent from the manifest.** `WORKFLOW_COMMANDS.md` describes `complete-sprint` as a command (lines 632-673). The manifest's retrospective phase lists only `retrospectives:complete-epic`. There is a `commands/project/retrospectives/complete-sprint.md` implementation file but no `.yaml` definition file for it. This is either a manifest omission or the command was removed without updating the docs. - **Common Ground absent.** The manifest includes `common-ground` as a utility command. `WORKFLOW_COMMANDS.md` does not mention it at all, despite its relevance to the workflow (it can be invoked at any point). - **Monolithic structure.** At 876 lines, the file tries to be both a conceptual introduction and a complete reference. The mermaid diagrams and process descriptions serve a "getting started" reader, while the checkpoint tables and integration points serve a "deep reference" reader. These audiences need different documents. **Recommendations:** 1. Add the Intake phase to `WORKFLOW_COMMANDS.md` or explicitly state it is a pre-workflow phase documented elsewhere. 2. Resolve the command naming inconsistency: pick one canonical form (the YAML `command` identifier) and use it consistently, with aliases noted parenthetically. 3. Either add `complete-sprint` to the manifest YAML (with a `.yaml` definition file) or remove it from `WORKFLOW_COMMANDS.md`. 4. Add a brief mention of `common-ground` as a utility command available during any phase. 5. For the Astro site, split this into a conceptual overview page and individual command reference pages. --- ### 1.2 `docs/workflow/*.md` (Phase Overviews and Command Descriptions) **Strengths:** - Clean, consistent structure across all 18 files. Every phase overview has Purpose, Commands table, Outputs, Prerequisites, and Next Steps. Every command description has Overview, Inputs table, Outputs table, Prerequisites, and Next Steps. - Inputs and outputs match the YAML definitions exactly in all files reviewed. This is strong evidence of either co-generation or disciplined manual maintenance. - Next Steps sections create a navigable chain: each doc tells you where to go next, forming a complete user journey. - Status badges (`**Status:** Planned`) on intake commands clearly communicate availability. **Weaknesses:** - **No common-ground phase overview.** There is a `docs/workflow/common-ground.md` command description, but no phase overview that contextualizes it. The manifest lists it under `utilities:`, not under a phase. The doc structure treats it as though it belongs to a phase. - **No `complete-sprint` description.** There is no `docs/workflow/retrospective-complete-sprint.md`. The retrospective phase overview mentions only `complete-epic`. If `complete-sprint` is a valid command, it needs a description doc. - **Phase names are inconsistent.** The manifest uses `retrospective` (singular). `WORKFLOW_COMMANDS.md` uses `Retrospectives` (plural). The phase overview file is `retrospective-phase.md` (singular). The command prefix in the manifest is `retrospectives:complete-epic` (plural). This inconsistency will cause confusion in code, docs, and URL generation. - **Relative links may break in a docs site context.** All Next Steps links use relative paths like `[Planning Phase](planning-phase.md)`. These work within the `docs/workflow/` directory but will need transformation for a docs site with different URL structures. **Recommendations:** 1. Decide whether `complete-sprint` exists in the system. If yes, create `docs/workflow/retrospective-complete-sprint.md` and add it to the manifest. If no, remove all references. 2. Standardize singular vs. plural: the manifest phase name, the YAML command prefix, the docs directory name, and the file naming convention should all agree. 3. Treat `common-ground` as a standalone utility in the docs structure (not shoehorned into a phase pattern). --- ### 1.3 `docs/COMMON_GROUND.md` **Strengths:** - Exceptionally well-written conceptual documentation. The Background & Motivation section (lines 16-41) provides genuine insight into the design rationale. - The two-phase flow diagram (lines 69-88) clearly illustrates the interactive process. - The confidence tiers (ESTABLISHED, WORKING, OPEN) are well-defined with practical examples and behavior descriptions. - The use cases section (lines 328-372) maps real scenarios to specific command flags. **Weaknesses:** - **Typo on line 176.** "groundin file" should be "grounding file." - **Overlap with README.** The README (lines 182-227) duplicates the confidence tier explanation and the `--graph` mermaid example. When this content moves to a docs site, the README version should be a brief pointer. - **No link to the workflow docs.** The Related Documentation section links to `WORKFLOW_COMMANDS.md` and `ATLASSIAN_MCP_SETUP.md`, but does not link to the `docs/workflow/common-ground.md` command description or the YAML definition. A reader in the workflow mindset has no bridge from here to the workflow system. - **No link FROM workflow docs.** `WORKFLOW_COMMANDS.md` does not mention or link to `COMMON_GROUND.md` at all. The two documentation trees are disconnected. **Recommendations:** 1. Fix the "groundin file" typo. 2. Add a link to `docs/workflow/common-ground.md` in the Related Documentation section. 3. Add a link to `docs/COMMON_GROUND.md` from within `WORKFLOW_COMMANDS.md` (perhaps in a "Utility Commands" section). 4. For the Astro site, deduplicate the README and `COMMON_GROUND.md` versions of the confidence tier explanation. --- ### 1.4 `docs/ATLASSIAN_MCP_SETUP.md` **Strengths:** - Excellent task-oriented structure. A user can follow from top to bottom and end up with a working setup. - Covers both Cloud and Server/Data Center configurations. - The Quick Start Checklist (lines 453-461) is a useful verification artifact. - Security considerations are thorough: credential protection, read-only mode, space/project filtering, audit trail, and token revocation. - Environment variable reference tables (lines 421-449) serve as a quick lookup. **Weaknesses:** - **Only linked from README and COMMON_GROUND.md.** `WORKFLOW_COMMANDS.md` does not link to this guide despite requiring Atlassian integration for all non-intake commands. A user reading the workflow docs and encountering Jira/Confluence references has no pointer to setup instructions. - **Docker-only approach.** The guide assumes Docker. If a user cannot or does not want to run Docker, there is no alternative path (e.g., `npx` or `pip` installation of the MCP server). - **No version pinning guidance.** The guide uses `:latest` for the Docker image. For production workflows, this is risky. A note about pinning to a specific version would be prudent. **Recommendations:** 1. Add a link to `ATLASSIAN_MCP_SETUP.md` from the Integration Points section of `WORKFLOW_COMMANDS.md`. 2. Add a note about version pinning for the Docker image. 3. Mention alternatives to Docker if available, or explicitly state Docker is required. --- ### 1.5 `docs/local_skill_development.md` **Strengths:** - Solves a real problem clearly: how to test skill changes without releasing. - The symlink workflow is well-explained with exact commands. - Caveats section (lines 96-113) proactively addresses the most likely failure modes. - Quick Reference section (lines 132-149) provides copy-paste commands. **Weaknesses:** - **Orphaned document.** No other document in the project links to this file. It is not referenced from README.md, CONTRIBUTING.md, or any guide. A contributor who needs it will not find it through navigation. - **No mention of the workflow system.** The guide covers skill development but says nothing about developing or testing workflow commands. Given that commands have a parallel structure (YAML definitions, description docs, implementation `.md` files), a contributor working on workflow commands has no equivalent guide. - **Placeholder paths.** The guide uses ``, ``, `` as placeholders without providing a concrete example of what these look like for the claude-skills project specifically. **Recommendations:** 1. Link this file from CONTRIBUTING.md and README.md (Documentation section). 2. Add a section or separate document for workflow command development. 3. Include one concrete example with actual claude-skills paths alongside the generic placeholders. --- ### 1.6 `commands/workflow-manifest.yaml` **Strengths:** - Clean DAG structure with typed dependency strengths (`required` vs. `recommended`). - `optional: true` on discovery phase correctly models the skippable nature of that phase. - `external_skills` reference to `feature-forge` documents the cross-cutting dependency. - `run_once: true` on intake correctly distinguishes project-level from epic-level phases. **Weaknesses:** - **Missing `complete-sprint`.** The retrospective phase lists only `retrospectives:complete-epic`. The `complete-sprint` command exists as an implementation `.md` file but has no YAML definition and no manifest entry. This is the single largest manifest/docs mismatch. - **No YAML definition files for intake commands exist as `.md` implementation files.** The YAML `path` fields point to `commands/intake/document-codebase.md`, `commands/intake/capture-behavior.md`, and `commands/intake/create-system-description.md`. None of these files exist on disk. The YAML `status: planned` field signals this is expected, but the schema documentation says "`Must resolve to an existing file when status: existing`" -- so the `planned` status makes this valid. However, the schema doc does not explicitly state that `planned` status exempts the path resolution rule. - **Phase name mismatch.** The manifest uses `retrospective` (singular) but the command identifiers use `retrospectives:` (plural). **Recommendations:** 1. Resolve the `complete-sprint` question: add it to the manifest or remove the orphaned `.md` file. 2. Make the planned-status path exemption explicit in the schema documentation. 3. Align the phase name and command prefix (both singular or both plural). --- ### 1.7 Command YAML Definitions (Sample of 6) **Strengths:** - 100% schema compliance across all 12 files reviewed. Every file has `command`, `phase` (where applicable), `path`, `description`, `inputs`, `outputs`, `requires`, `status`, `argument-hint`, and `repeat`. - Input/output types are consistent and match the schema's allowed values. - The `description` field correctly points to the corresponding `docs/workflow/*.md` file in every case. - `requires` fields accurately distinguish commands needing ticketing/documentation backends from those that do not. **Weaknesses:** - **Intake commands point to non-existent implementation files.** `commands/intake/document-codebase.yaml` has `path: commands/intake/document-codebase.md` but this file does not exist. Same for the other two intake commands. The `status: planned` field explains this, but a CI validation step should catch it. - **`common-ground.yaml` has no `phase` field.** This is correct per the schema (utilities omit `phase`), but is inconsistent with the schema documentation which lists `phase` as required. The schema doc should explicitly state that `phase` is omitted for utility commands. **Recommendations:** 1. Add a CI validation that verifies `path` files exist when `status: existing`. 2. Clarify in the schema documentation that `phase` is omitted for utility commands. --- ## 2. Workflow Documentation Gap Analysis ### Commands Documented vs. Commands in YAML | Command | YAML Def | Manifest | `WORKFLOW_COMMANDS.md` | `docs/workflow/` desc | Implementation `.md` | |---------|----------|----------|------------------------|----------------------|---------------------| | `intake:document-codebase` | Yes | Yes | **NO** | Yes | **NO** (planned) | | `intake:capture-behavior` | Yes | Yes | **NO** | Yes | **NO** (planned) | | `intake:create-system-description` | Yes | Yes | **NO** | Yes | **NO** (planned) | | `discovery:create` | Yes | Yes | Yes | Yes | Yes | | `discovery:synthesize` | Yes | Yes | Yes | Yes | Yes | | `discovery:approve` | Yes | Yes | Yes | Yes | Yes | | `planning:epic-plan` | Yes | Yes | Yes | Yes | Yes | | `planning:impl-plan` | Yes | Yes | Yes | Yes | Yes | | `execution:execute-ticket` | Yes | Yes | Yes | Yes | Yes | | `execution:complete-ticket` | Yes | Yes | Yes | Yes | Yes | | `retrospectives:complete-epic` | Yes | Yes | Yes | Yes | Yes | | `retrospectives:complete-sprint` | **NO** | **NO** | Yes | **NO** | Yes | | `common-ground` | Yes | Yes (utility) | **NO** | Yes | Yes | ### Phase Overviews | Phase | Manifest | `WORKFLOW_COMMANDS.md` | `docs/workflow/` overview | |-------|----------|------------------------|--------------------------| | Intake | Yes | **NO** | Yes | | Discovery | Yes | Yes | Yes | | Planning | Yes | Yes | Yes | | Execution | Yes | Yes | Yes | | Retrospective | Yes | Yes | Yes | ### Key Gaps 1. **Intake phase entirely absent from `WORKFLOW_COMMANDS.md`.** Three commands undocumented in the primary reference. 2. **`complete-sprint` exists as implementation and in `WORKFLOW_COMMANDS.md` but has no YAML definition or manifest entry.** This is a ghost command -- documented but not formally defined. 3. **`common-ground` absent from `WORKFLOW_COMMANDS.md`.** Documented in its own guide (`COMMON_GROUND.md`) but invisible in the workflow reference. 4. **README claims 9 workflows.** The manifest defines 12 commands + 1 utility. The README's Project Workflow Commands table lists 9 commands (matching `WORKFLOW_COMMANDS.md`, not the manifest). The count depends on whether intake and common-ground are included. --- ## 3. Proposed Restructuring for Astro + Starlight ### Content Architecture The existing three-layer documentation (README overview, `WORKFLOW_COMMANDS.md` reference, `docs/workflow/` descriptions) should map to Starlight's built-in structure. ``` Site Structure: /workflows/ <- Landing page: DAG diagram, phase cards /workflows/intake/ <- Phase overview (from intake-phase.md) /workflows/intake/document-codebase/ <- Command page (generated from YAML + description .md) /workflows/intake/capture-behavior/ /workflows/intake/create-system-description/ /workflows/discovery/ <- Phase overview /workflows/discovery/create/ /workflows/discovery/synthesize/ /workflows/discovery/approve/ /workflows/planning/ /workflows/planning/epic-plan/ /workflows/planning/impl-plan/ /workflows/execution/ /workflows/execution/execute-ticket/ /workflows/execution/complete-ticket/ /workflows/retrospective/ /workflows/retrospective/complete-epic/ /workflows/retrospective/complete-sprint/ <- Only if formalized /utilities/common-ground/ <- Standalone utility page /guides/atlassian-setup/ <- Setup guide /guides/local-development/ <- Development workflow /guides/getting-started/ <- New: entry point for new users ``` ### Page Templates **Phase Overview Page** (generated from `docs/workflow/{phase}-phase.md` + manifest data): - Purpose statement - DAG position indicator (which phases come before/after) - Command cards with status badges - Prerequisites - Next phase link **Command Reference Page** (generated from YAML definition + `docs/workflow/{command}.md`): - Command signature with argument hints - Status badge (existing/planned/deprecated) - Inputs table (from YAML) - Outputs table (from YAML) - Requirements badges (ticketing, documentation) - Overview narrative (from description `.md`) - Prerequisites - Next Steps - Phase breadcrumb **Utility Page** (for commands like `common-ground`): - Same as command reference but without phase context - Links to the conceptual guide (`COMMON_GROUND.md`) ### What to Retire - **`WORKFLOW_COMMANDS.md` as a single file.** Its content splits across the phase overview pages and command reference pages. The mermaid diagrams move to the phase overview pages. The checkpoint system documentation becomes a standalone guide at `/guides/checkpoints/`. The integration points section becomes `/guides/atlassian-setup/` (merged with current `ATLASSIAN_MCP_SETUP.md`). - **Duplicated content in README.** The Project Workflow Commands section in README becomes a brief paragraph pointing to `/workflows/`. The `common-ground` section in README becomes a brief paragraph pointing to `/utilities/common-ground/`. ### What to Create 1. **Getting Started guide.** The biggest gap for new users. Currently, a user must read: README (installation) -> ATLASSIAN_MCP_SETUP.md (MCP config) -> WORKFLOW_COMMANDS.md (understand the system) -> docs/workflow/ files (individual commands). A single "Getting Started with Workflows" guide should walk through: install -> configure Atlassian -> run your first planning cycle. 2. **Checkpoint System guide.** Currently buried in `WORKFLOW_COMMANDS.md`. Deserves its own page since it is a cross-cutting concern. 3. **Workflow FAQ/Troubleshooting.** Common questions like "Can I skip discovery?" or "What if a ticket has no implementation details?" are answered implicitly in the docs but not collected anywhere. --- ## 4. Recommendations for Standalone Pages Each `docs/workflow/*.md` file is close to being a usable standalone page already. To make them fully independent: ### Required Additions Per Command Page 1. **Command invocation syntax.** Add the actual slash-command syntax at the top. Currently the description docs do not include how to invoke the command (e.g., `/project:discovery:create `). Only `WORKFLOW_COMMANDS.md` has this. 2. **Phase context breadcrumb.** Add a one-line note: "Part of the Discovery phase. Comes after `intake:create-system-description`. Feeds into `discovery:synthesize`." 3. **Requirements callout.** Add a visible callout for external dependencies: "Requires: Jira, Confluence. See [Atlassian Setup Guide](...)." 4. **Status visibility.** The intake commands have a status badge, but the existing commands do not explicitly state they are available. Add a consistent status indicator to all pages. ### Required Additions Per Phase Page 1. **DAG context.** Add which phases depend on this phase and which this phase depends on (pulling from the manifest's `depends_on` field). 2. **Skip conditions.** For optional phases (discovery), state when and how to skip. 3. **External skill dependencies.** The manifest's `external_skills` field (e.g., feature-forge as prerequisite for discovery) should be surfaced in the phase overview. --- ## 5. Priority Ranking ### Critical (Must fix before next release) 1. **Resolve `complete-sprint` status.** Either add YAML definition + manifest entry, or remove from `WORKFLOW_COMMANDS.md` and delete the orphaned implementation file. The current state is contradictory. 2. **Fix phase name inconsistency.** `retrospective` (manifest phase name) vs. `retrospectives` (command prefix). This will cause bugs in any automated tooling that derives one from the other. 3. **Add Intake phase to `WORKFLOW_COMMANDS.md`.** Three commands are invisible to anyone reading the primary workflow reference. ### High (Should fix for docs site launch) 4. **Standardize command naming.** Establish one canonical name per command and document aliases. Current state: `create-epic-discovery` (WORKFLOW_COMMANDS.md) vs. `discovery:create` (manifest) vs. `/project:discovery:create-epic-discovery` (full invocation path). 5. **Cross-link `COMMON_GROUND.md` and `WORKFLOW_COMMANDS.md`.** These are companion documents with zero cross-references. 6. **Cross-link `ATLASSIAN_MCP_SETUP.md` from `WORKFLOW_COMMANDS.md` Integration Points section.** A reader encountering Jira/Confluence requirements needs the setup guide. 7. **Link `local_skill_development.md` from CONTRIBUTING.md and README.** Currently orphaned. 8. **Fix "groundin file" typo in `COMMON_GROUND.md` line 176.** 9. **Add invocation syntax to each `docs/workflow/` command description.** Currently, only `WORKFLOW_COMMANDS.md` shows how to actually invoke commands. ### Medium (Should fix for quality) 10. **Clarify schema documentation for planned-status path exemption.** The schema says `path` must resolve to an existing file but does not mention the `planned` exemption. 11. **Clarify schema documentation for utility command phase omission.** The schema says `phase` is required but utilities omit it. 12. **Create a Getting Started guide.** New users face a fragmented onboarding path across 4+ documents. 13. **Deduplicate README and `COMMON_GROUND.md` confidence tier explanations.** Same content appears in both. 14. **Add CI validation for YAML path resolution.** Catch broken `path` references automatically. 15. **Update README workflow count.** The README claims 9 workflows. The actual count depends on scope definition. Clarify what "workflow" means (commands? phases?) and update. ### Nice-to-Have (Future improvement) 16. **Add a workflow FAQ/troubleshooting page.** Collect implicit answers to common questions. 17. **Add version pinning guidance to `ATLASSIAN_MCP_SETUP.md`.** The `:latest` Docker tag is convenient but risky. 18. **Add a workflow command development guide.** `local_skill_development.md` covers skills but not commands. 19. **Create a checkpoint system standalone guide.** Currently buried in `WORKFLOW_COMMANDS.md` and worth surfacing independently. 20. **Add concrete path examples to `local_skill_development.md`.** Replace generic `//` with actual claude-skills values. --- ## 6. Cross-Reference Matrix Documents that should link to each other but currently do not: | From | To | Missing Link | |------|----|--------------| | `WORKFLOW_COMMANDS.md` | `COMMON_GROUND.md` | No mention of common-ground utility | | `WORKFLOW_COMMANDS.md` | `ATLASSIAN_MCP_SETUP.md` | No link in Integration Points section | | `WORKFLOW_COMMANDS.md` | `docs/workflow/intake-phase.md` | Entire intake phase absent | | `WORKFLOW_COMMANDS.md` | `docs/workflow/common-ground.md` | No utility commands section | | `COMMON_GROUND.md` | `docs/workflow/common-ground.md` | No link to the workflow-format description | | `README.md` | `docs/local_skill_development.md` | Not listed in Documentation section | | `CONTRIBUTING.md` | `docs/local_skill_development.md` | Not linked for contributors | | `SKILLS_GUIDE.md` | `WORKFLOW_COMMANDS.md` | No cross-reference to workflows | | `docs/workflow/retrospective-phase.md` | `complete-sprint` | Phase overview only lists `complete-epic` | --- ## 7. Summary Metrics | Metric | Count | |--------|-------| | Total docs files audited | 26 | | Total YAML definitions audited | 12 | | Documentation gaps found | 6 (intake in WORKFLOW_COMMANDS, complete-sprint YAML, common-ground in WORKFLOW_COMMANDS, local dev orphan, cross-links, invocation syntax) | | Naming inconsistencies found | 3 (command names, phase singular/plural, workflow count) | | Broken or missing cross-references | 9 (see matrix above) | | Typos found | 1 | | Files with no inbound links | 2 (`local_skill_development.md`, `docs/workflow/workflow-definition-schema.md`) | | Critical priority items | 3 | | High priority items | 6 | | Medium priority items | 6 | | Nice-to-have items | 5 | --- ## File: docs/ideas/documentation-site.md # Documentation Site Proposal for a standalone documentation site for the claude-skills project. --- ## Motivation ### The Problem All project content currently lives on `github.com/jeffallan/claude-skills`. This means: - **No Google Search Console access** — can't see which queries drive traffic, can't submit sitemaps, can't control indexing - **No control over meta tags** — page titles, OpenGraph, structured data are all GitHub's defaults - **One giant README** — 65 skills, 9 workflows, 356 reference files collapsed into a single page - **No individual skill URLs** — a skill can't be linked to, shared, or indexed independently ### The Opportunity Current traffic data (2-week snapshot, Jan 2026) shows strong organic discovery already happening without any SEO effort: | Source | Views | Unique Visitors | |--------|-------|-----------------| | Google | 5,532 | 1,026 | | github.com | 2,646 | 516 | | t.co (Twitter/X) | 570 | 208 | | statics.teams.cdn.office.net (MS Teams) | 170 | 37 | | chatgpt.com | 100 | 22 | | claude.ai | 58 | 12 | | com.reddit.frontpage | 49 | 12 | | bytedance.larkoffice.com (ByteDance internal) | 33 | 6 | Additional metrics: 197 stars, 9.5k downloads (skills.sh), 4,560 unique cloners, 4,008 unique visitors in 2 weeks. Key signals: - **Enterprise adoption** — traffic from Microsoft Teams and ByteDance's internal Lark platform indicates workplace sharing - **AI platform discovery** — ChatGPT and Claude.ai are referring users organically - **Google dominance** — 1,026 unique visitors from search with zero SEO optimization suggests significant upside once proper pages exist ### The Insight: Skill Linking = Internal Link Graph Issue #69 (Skill Metadata Enhancement) plans to formalize the existing static `## Related Skills` sections into typed `metadata.*` relationships (complementary, prerequisite, alternative). This metadata serves two consumers simultaneously: 1. **Agent runtime** — Claude follows structured links to load related skills contextually 2. **Documentation site** — The same relationships become real `` links between skill pages, creating a dense internal link graph This is exactly what both classic SEO and LLM retrieval reward: - Google uses internal link structure to understand page relationships and distribute authority - LLMs doing retrieval follow link structure to build richer context about what the project offers **One schema, two consumers.** Relationship data written once in YAML generates both runtime cross-references and HTML internal links. Issue #100 (Cross-Reference Validation) also becomes dual-purpose — it validates both agent behavior and docs site link integrity. --- ## Hard Requirement: Dual-Format Serving (HTML + Markdown) The site MUST serve every content page in two formats from the same URL: - **HTML** — for human consumption (styled, navigable, searchable) - **Markdown** — for agent consumption (clean, context-efficient, directly loadable) Format selection via content negotiation (`Accept: text/markdown`) or URL convention (e.g., `/skills/react-expert.md` or `?format=md`). ### Why This Matters The docs site isn't just for humans. Agents are a first-class consumer. When an agent needs to understand what `react-expert` does, it should be able to fetch the markdown directly from the docs site URL — not scrape HTML and hope the conversion is clean. This turns the entire docs site into an **agent-consumable API**: - `llms.txt` becomes a routing file pointing agents to markdown endpoints for every skill and command - An agent can fetch `/skills/react-expert.md` and get the same content that generates the HTML page — no lossy HTML-to-markdown conversion - The skill's reference files are available at `/skills/react-expert/server-components.md` — agents can selectively load exactly what they need - Workflow commands with typed inputs/outputs are available as structured markdown at `/commands/discovery/create.md` ### Implementation Approaches **Option A: Static .md file co-generation** - During build, output both `index.html` and `index.md` for every page - Simple, no runtime logic, works with any CDN/static host - URL convention: `/skills/react-expert/` (HTML) vs `/skills/react-expert/index.md` (markdown) **Option B: Content negotiation middleware** - Server checks `Accept` header and returns appropriate format - Cleaner URLs but requires a server or edge function (not pure static) **Option C: Query parameter** - `/skills/react-expert/?format=md` returns markdown - Works with edge functions on static hosts (Cloudflare Pages, Vercel) **Recommendation:** Option A (static co-generation) as the baseline — it works everywhere, requires no runtime, and the `.md` files are just the source markdown the site was built from. Options B or C can be layered on later if cleaner URLs are desired. ### Impact on Site Generator Selection This requirement narrows the field. The generator must support outputting both HTML and raw markdown for each content page. This is a build-step concern, not a runtime concern — the generator (or a post-build script) writes both formats to the output directory. ### Impact on llms.txt With dual-format serving, `llms.txt` evolves from a static summary into a structured index with direct markdown URLs: ``` # Claude Skills > 65 specialized skills for full-stack developers ## Skills - [React Expert](/skills/react-expert/index.md): React 18+ with Server Components, hooks, state management - [NestJS Expert](/skills/nestjs-expert/index.md): NestJS modules, controllers, services, TypeORM/Prisma - [Python Pro](/skills/python-pro/index.md): Python 3.11+ with type safety, async, pytest ... ## Workflows - [Discovery Phase](/workflows/discovery/index.md): Research, synthesize, and approve requirements - [Planning Phase](/workflows/planning/index.md): Analyze codebase and create execution plans ... ``` Every line is a fetchable markdown URL. An agent reading `llms.txt` can navigate the entire project without touching HTML. --- ## Architecture: The Autodoc Analogy The project already has the equivalent of Python's autodoc infrastructure: | Python autodoc | Claude Skills equivalent | |---|---| | Package | Phase (intake, discovery, planning, execution, retrospective) | | Module | Skill or Command | | Docstring | `SKILL.md` body / command description `.md` | | Type annotations | YAML `inputs`/`outputs` with typed fields | | `__init__.py` exports | `workflow-manifest.yaml` | | Cross-references | `metadata.*` relationships, `external_skills`, `depends_on` | | Module index page | Skills overview / workflow DAG visualization | | Sub-module docs | Reference files under each skill | A static site generator consumes the existing YAML definitions and markdown files directly — minimal glue code, not a rewrite. ### Content Sources (Already Exist) | Source | Generates | |--------|-----------| | `skills/*/SKILL.md` frontmatter | Skill index page, per-skill metadata cards | | `skills/*/SKILL.md` body | Individual skill pages | | `skills/*/references/*.md` | Sub-pages under each skill | | `commands/*/*.yaml` | Command reference pages with typed inputs/outputs | | `commands/workflow-manifest.yaml` | DAG visualization, phase overview pages | | `docs/workflow/*.md` | Phase and command description pages | | `SKILLS_GUIDE.md` | Category navigation, decision trees | | `README.md` | Landing page (simplified) | | `CHANGELOG.md` | Release history page | ### Content to Create | Content | Purpose | |---------|---------| | `llms.txt` | Structured project summary for LLM discoverability | | Landing page | Simplified hero + quick start (not the full README) | | Search / filter UI | Filter skills by category, language, framework | | Sitemap | Auto-generated from skill/command pages | | OpenGraph meta tags | Per-skill social previews for link sharing | --- ## Proposed Site Structure ``` / ← Landing page (hero, quick start, stats) /skills/ ← Skill index (filterable by category) /skills/react-expert/ ← Generated from SKILL.md /skills/react-expert/server-components/ ← Generated from references/ /skills/react-expert/performance/ ← Generated from references/ /commands/ ← Command index /commands/common-ground/ ← Generated from command YAML + description .md /workflows/ ← DAG visualization of all phases /workflows/discovery/ ← Phase overview (from docs/workflow/discovery-phase.md) /workflows/discovery/create/ ← Command detail (from YAML + description .md) /guide/ ← Skills guide (from SKILLS_GUIDE.md) /guide/decision-trees/ ← When to use which skill /changelog/ ← Release history /llms.txt ← LLM-consumable project summary ``` Each skill page would include: - Frontmatter metadata rendered as structured sidebar (role, scope, triggers) - Skill body (workflow, constraints, output templates) - Related Skills as internal links (from `metadata.*` once #69 lands; from static sections until then) - Reference files as sub-navigation - "Install this skill" code snippet Each command page would include: - Inputs table (from YAML `inputs` with types) - Outputs table (from YAML `outputs` with types) - Requirements badges (ticketing, documentation) - Phase context (where it sits in the DAG) - Upstream/downstream commands --- ## AI Discoverability: llms.txt Add an `llms.txt` file to both the repo root and the docs site root. Content auto-generated from: - Skill names, descriptions, and triggers (from SKILL.md frontmatter) - Workflow phases and command summaries (from workflow-manifest.yaml) - Project stats (skill count, reference count, framework coverage) - Installation instructions This gives LLM retrieval systems (Perplexity, ChatGPT browsing, Claude.ai web search) a structured index without requiring them to parse the full site. --- ## Plan: Documentation Review and Restructure ### Phase 1: Audit Current Documentation Use a technical writing agent to: 1. **Inventory all existing docs** — README, SKILLS_GUIDE, CONTRIBUTING, docs/*.md, workflow docs, skill SKILL.md files 2. **Identify redundancy** — content duplicated across README, SKILLS_GUIDE, and individual docs 3. **Identify gaps** — missing docs, outdated sections, broken cross-references 4. **Assess voice consistency** — do all docs follow the same tone, structure, terminology? 5. **Map content to site structure** — which existing doc maps to which site page? ### Phase 2: Content Restructuring 1. **Separate concerns** — README becomes a short landing page pointing to the docs site; detailed content moves to docs 2. **Deduplicate** — single source of truth for each topic; other locations link to it 3. **Standardize structure** — every skill page follows the same template; every command page follows the same template 4. **Write missing content** — landing page copy, category descriptions, getting started guide 5. **Refresh stale content** — update any sections referencing old versions or outdated patterns ### Phase 3: Complete #69 — Skill Metadata Enhancement (BLOCKING) **This phase must complete before site generator setup.** The Astro content collection schemas depend on the finalized metadata structure. Building the site before #69 means defining the schema twice — once provisionally, then again when the metadata spec lands. #69 determines: - What fields exist in SKILL.md frontmatter vs. the `metadata.*` key - How relationship types are structured (complementary, prerequisite, alternative) - Whether domain tags, compatibility info, or other new metadata lives under `metadata.*` - The finalized schema that both the agent runtime AND the docs site consume The content collection schema, the internal link graph, the per-page meta tags, and the `llms.txt` index all derive from whatever #69 produces. Get the data model right first. **What CAN proceed in parallel with #69:** - Phase 1 (audit) and Phase 2 (content restructuring) — these are about the docs content, not the schema - Evaluating Astro + Starlight with a proof-of-concept using current frontmatter fields - Setting up the repo structure for the docs site (Astro project scaffolding) ### Phase 4: Site Generator Setup — Astro + Starlight #### Decision: Astro + Starlight After evaluating Docusaurus, Hugo, MkDocs Material, and VitePress against the hard requirements (dual-format output, auto-generation from YAML/markdown, SEO), **Astro + Starlight** is the recommended choice. **Why Astro wins for this project:** | Requirement | How Astro Handles It | |---|---| | **Dual-format (HTML+MD)** | Custom endpoints serve raw markdown at `/skills/react-expert/index.md` alongside HTML at `/skills/react-expert/`. Supported pattern, not a hack. | | **Auto-gen from YAML/SKILL.md** | Content collections: define a schema matching SKILL.md frontmatter, point at `skills/*/SKILL.md`, pages are auto-generated with typed data. Command YAML files become a second collection. | | **SEO out of the box** | 100/100 Lighthouse scores. Auto sitemap, meta tags, OpenGraph. Starlight adds search, navigation, TOC. | | **Zero JS shipped** | Pure static HTML by default. No SPA hydration overhead. Instant loads for developers hitting docs from Google or LLM referrals. | | **Social cards** | Existing `scripts/capture-screenshot.js` can be adapted for per-page OG images. | **Why not the others:** - **Docusaurus** — Best SEO defaults, but ships a React SPA (unnecessary JS weight) and has no native content collection concept. Dual-format requires a custom plugin. - **Hugo** — Only SSG with first-class dual-format output (custom output formats). But Go templating for auto-generation from structured YAML is more manual wiring than Astro content collections. Strong fallback if Astro proves problematic. - **MkDocs Material** — Unique auto social card generation, but weakest on dual-format and programmatic page generation. Too opinionated about directory structure. - **VitePress** — Fast and clean, but less mature plugin ecosystem and no content collections. **Ecosystem fit:** The project targets TypeScript/JavaScript developers. Astro uses TypeScript natively. Existing Python scripts (`validate-skills.py`, `update-docs.py`) remain as CI validation — the site generator doesn't replace them. #### How Content Collections Map to This Project ``` // Astro content collection schema (conceptual) // IMPORTANT: Final schema depends on #69 metadata enhancement skills collection: source: skills/*/SKILL.md schema: name: string ← from frontmatter description: string ← from frontmatter (max 1024 chars) triggers: string[] ← from frontmatter role: enum ← specialist | expert | architect scope: enum ← implementation | review | design | ... output-format: enum ← code | document | report | ... metadata: ← from #69, structure TBD related: object[] ← typed relationships (complementary, prerequisite, etc.) domain: string[] ← domain tags ... commands collection: source: commands/**/*.yaml schema: command: string ← phase:action identifier phase: string ← intake | discovery | planning | ... inputs: object[] ← typed input definitions outputs: object[] ← typed output definitions requires: string[] ← ticketing | documentation status: enum ← existing | planned | deprecated workflows collection: source: commands/workflow-manifest.yaml schema: phases: object ← DAG definition with depends_on edges utilities: object[] ← on-demand commands ``` ### Phase 5: Build and Deploy 1. Define Astro content collection schemas from finalized #69 metadata spec 2. Build page templates for skills, commands, workflows 3. Implement dual-format endpoints (HTML + markdown per page) 4. Generate `llms.txt` from content collections at build time 5. Deploy to GitHub Pages with custom domain 6. Submit sitemap to Google Search Console 7. Add sponsor badges to site and repo README 8. Set up GitHub Actions for auto-deploy on push to main ### Phase 6: Ongoing Maintenance - CI check: validate that every skill/command has a corresponding docs page - CI check: validate internal links (extends #100 cross-reference validation) - Auto-regenerate `llms.txt` on release - Auto-regenerate sitemap on content changes - Content collection schema validation catches broken frontmatter at build time --- ## Dependency Chain ``` #69 Skill Metadata Enhancement ├── Docs site content collection schemas (can't finalize without #69) ├── #65 Cross-Domain Recommendations (content work, depends on #69) ├── #66 Enhanced Routing Logic (better descriptions = better page titles) └── Internal link graph (relationship metadata → links) #100 Cross-Reference Validation └── Docs site link validation (same check, dual purpose) #68 Skill Dependency Mapping └── DAG visualization page on docs site Phase 1 (Audit) ──────────────────── can start NOW Phase 2 (Content restructuring) ──── can start NOW Phase 3 (#69 metadata) ──────────── BLOCKING for site schema Phase 4 (Astro setup) ───────────── after #69 Phase 5 (Build and deploy) ──────── after Phase 4 Phase 6 (Maintenance) ───────────── ongoing after Phase 5 ``` --- ## Open Questions 1. **Custom domain?** — `docs.claudeskills.dev`, `skills.jeffallan.dev`, or subdirectory of existing site? 2. **Versioned docs?** — Do we need docs for multiple versions, or just latest? 3. **Search** — Starlight built-in search vs. Algolia DocSearch (free for open source)? 4. **Docs site repo** — Same repo (monorepo with `/site` directory) or separate repo? --- ## File: docs/prompts/discovery-for-feature-forge.md # Multi-Agent Discovery Prompt for Feature Forge > **Purpose:** Use this prompt to trigger parallel skill-invoked discovery across > multiple domains before starting a Feature Forge specification workshop. > The collected findings become input context for the Feature Forge interview, > replacing guesswork with concrete technical evidence. --- ## Prompt ``` I need to define a new feature: [FEATURE DESCRIPTION]. Before we start the Feature Forge specification workshop, run parallel discovery across the relevant domains to build technical context. Launch the following Task subagents concurrently — each should invoke its respective skill and return a focused summary: 1. **Architecture Discovery** — Launch a Task subagent (general-purpose) that invokes the `architecture-designer` skill to: - Identify which system components this feature touches - Map integration points and data flows - Flag architectural constraints or trade-offs - Recommend patterns that fit the existing system 2. **Security Discovery** — Launch a Task subagent (general-purpose) that invokes the `security-reviewer` skill to: - Identify authentication and authorization requirements - Flag data sensitivity concerns (PII, PCI, GDPR) - Surface OWASP-relevant risks for this feature type - Recommend security patterns and controls 3. **Codebase Discovery** — Launch a Task subagent (Explore) to: - Search for existing patterns, components, or utilities related to this feature - Identify code conventions and abstractions already in use - Find similar features that can serve as implementation templates - Note relevant test patterns and coverage expectations 4. **API/Integration Discovery** — Launch a Task subagent (general-purpose) that invokes the `api-designer` skill to: - Propose API surface area (endpoints, methods, payloads) - Identify existing API patterns to follow for consistency - Flag external service dependencies and rate limits - Recommend versioning and backwards-compatibility approach Wait for all subagents to complete, then: 1. **Synthesize** — Combine the findings into a structured discovery summary with sections for: Architecture, Security, Codebase Patterns, and API Surface. 2. **Identify Decisions** — List the key decisions that emerged from discovery (e.g., "sync vs async processing", "new table vs extend existing"). Present these as `AskUserQuestions` with structured options. 3. **Launch Feature Forge** — With the discovery context and user decisions in hand, invoke the `feature-forge` skill to begin the specification workshop. The interview should reference discovery findings rather than re-asking questions the subagents already answered. ``` --- ## Usage ### Basic Invocation Replace `[FEATURE DESCRIPTION]` with your feature summary: ``` I need to define a new feature: user-facing data export that supports CSV and JSON formats with scheduled recurring exports. Before we start the Feature Forge specification workshop, run parallel discovery... ``` ### Customizing Discovery Agents Not every feature needs all four discovery tracks. Tailor the subagent list: | Feature Type | Recommended Agents | |-------------|-------------------| | New UI feature | Codebase + Architecture | | New API endpoint | API/Integration + Security + Codebase | | Data pipeline | Architecture + Security + Codebase | | Auth/permissions | Security + Architecture + Codebase | | Full-stack feature | All four agents | ### Expected Output Flow ``` User provides feature description │ ├─→ [Parallel] Architecture Discovery ──→ Component map, constraints ├─→ [Parallel] Security Discovery ──────→ Auth reqs, data sensitivity ├─→ [Parallel] Codebase Discovery ──────→ Existing patterns, templates └─→ [Parallel] API Discovery ───────────→ Endpoint design, integrations │ ▼ Synthesized Discovery Summary │ ▼ AskUserQuestions: Key decisions from discovery │ ▼ Feature Forge Interview (informed by discovery context) │ ▼ EARS Specification Document ``` --- ## Design Rationale This prompt applies the **ReAct + Chain-of-Thought** pattern from prompt engineering: - **ReAct:** Each subagent acts as a reasoning-action step — it invokes a skill (action), collects findings (observation), then feeds results forward. - **Chain-of-Thought:** The synthesis step forces explicit reasoning about how discovery findings connect before entering the Feature Forge interview. - **Structured Elicitation:** Key decisions surface as `AskUserQuestions` with options derived from technical evidence, not assumptions. The parallel execution pattern reduces total discovery latency — all four agents run concurrently rather than sequentially asking the user about each domain. --- ## File: docs/skill-ideas/tarot.md # Tarot-Inspired Skill Ideas High-level concepts mapping tarot archetypes to agent behaviors. Each archetype provides a memorable invocation pattern and a distinct cognitive mode. --- ## The Fool (In Progress) **Archetype:** The court jester who speaks truth to power. **Purpose:** Domain-agnostic critical reasoning with 5 modes — Socratic questioning, Hegelian dialectic, pre-mortem, red teaming, and evidence audit. Uses `AskUserQuestions` for mode selection. **Trigger:** "play the fool", "devil's advocate", "challenge this" **Status:** Full plan at `docs/skill-ideas/the-fool.md` --- ## The Hermit **Archetype:** The seeker who withdraws to understand before acting. **Purpose:** Deep research and reflection. When you need to step back from implementation and truly understand something first. Systematic codebase archaeology, reading documentation thoroughly, tracing data flows end-to-end. The opposite of "let me just try something." **Trigger:** "I need to understand this before touching it" **Gap filled:** No existing skill enforces a read-only investigation phase before action. Debugging-wizard investigates bugs; The Hermit investigates *systems* — how they work, why they were built this way, what the original authors intended. **Possible modes:** - Trace a data flow end-to-end - Map the dependency graph of a concept - Reconstruct the decision history (git archaeology) - Build a mental model before proposing changes --- ## The Tower **Archetype:** Lightning strikes — the old structure falls so something better can rise. **Purpose:** Controlled demolition and rebuild. When something is fundamentally broken and incremental fixes won't work. Guides tearing down and rebuilding: legacy system replacement, major refactors, ripping out a bad abstraction. **Trigger:** "this needs to be torn down and rebuilt" **Gap filled:** Legacy-modernizer focuses on incremental migration (strangler fig). The Tower is for when incremental isn't viable — you need a clean break with a structured rebuild plan. **Possible modes:** - Blast radius assessment (what breaks if we remove this?) - Parallel build strategy (new system alongside old) - Cut-over planning (the moment of switch) - Rollback design (if the new thing fails) --- ## The Wheel of Fortune **Archetype:** The turning wheel — fate, chance, and multiple possible futures. **Purpose:** Scenario planning under genuine uncertainty. Not "what could go wrong" (that's The Fool's pre-mortem) but mapping multiple possible futures and building strategies robust across them. Decision-making when you genuinely don't know which way things will go. **Trigger:** "we don't know which way this will go" **Gap filled:** No existing skill handles multi-scenario planning. Architecture-designer evaluates trade-offs for a known context; The Wheel of Fortune plans for unknown contexts. **Possible modes:** - Scenario generation (3-4 plausible futures) - Strategy robustness testing (does this plan work across scenarios?) - Optionality analysis (which choice preserves the most future options?) - Trigger identification (what signals tell us which scenario is unfolding?) --- ## The Magician **Archetype:** Manifestation — turning idea into reality with the tools at hand. **Purpose:** Rapid prototyping and proof of concept. Takes an idea and manifests the simplest possible working version to test feasibility. Ruthlessly YAGNI. "Show me the smallest thing that proves this works." **Trigger:** "can we even do this?", "prove this works" **Gap filled:** Feature-forge defines requirements; The Magician skips requirements and builds the thinnest possible slice to answer a feasibility question. Complements feature-forge — use The Magician to validate assumptions *before* writing specs. **Possible modes:** - Feasibility spike (can the technology do this at all?) - Integration probe (can these two systems talk to each other?) - Performance experiment (will this approach scale?) - UX sketch (does this interaction model make sense?) --- ## The High Priestess **Archetype:** Intuition and hidden knowledge — seeing what others miss. **Purpose:** Pattern recognition and intuition translation. When something "feels wrong" but you can't articulate why. Translates gut feelings into concrete technical concerns. Examines code smells, architectural drift, naming inconsistencies — the subtle signals that something is off. **Trigger:** "something about this doesn't feel right" **Gap filled:** Code-reviewer checks against known standards. The High Priestess investigates the *unnamed* — the patterns that don't match, the drift from original intent, the subtle wrongness that no linter catches. **Possible modes:** - Code smell archaeology (what changed and when did it start drifting?) - Naming analysis (do the names still match what the code does?) - Architectural consistency (does this component belong here?) - Implicit contract detection (what undocumented assumptions does this code rely on?) --- ## The Star **Archetype:** The guiding light — hope, purpose, and true north. **Purpose:** North star alignment. When you're deep in implementation weeds and need to reconnect with the original vision. Checks current work against stated goals, user needs, and project values. Detects scope creep, gold plating, and mission drift. **Trigger:** "are we still building the right thing?" **Gap filled:** No existing skill checks alignment between work-in-progress and original intent. Feature-forge defines the target; The Star checks whether you're still pointed at it. **Possible modes:** - Goal alignment audit (does this PR serve the stated objective?) - Scope creep detection (what got added that wasn't in the spec?) - User value check (does the end user actually benefit from this work?) - Simplification pass (what can be removed and still deliver the value?) --- ## Death **Archetype:** Transformation — endings that enable new beginnings. **Purpose:** Graceful deprecation and migration. Not destruction (that's The Tower) but *transition*. Guides sunsetting features, migrating users, deprecation timelines, and backward compatibility strategies. The art of ending things well. **Trigger:** "we need to retire this" **Gap filled:** Overlaps with legacy-modernizer but with a different focus. Legacy-modernizer transforms old into new; Death manages the *ending* — communication, migration paths, timeline, and the social/organizational aspects of removing something people depend on. **Possible modes:** - Impact assessment (who uses this and how?) - Migration path design (where do users go instead?) - Deprecation timeline (warnings, soft removal, hard removal) - Tombstone documentation (why was this removed, and what replaced it?) --- ## The Emperor **Archetype:** Order, structure, authority — the rules of the realm. **Purpose:** Governance and standards enforcement. Audits a codebase or project against its own stated standards. Checks that conventions are followed, ADRs are respected, and architectural boundaries aren't violated. Not inventing rules — enforcing the ones already committed to. **Trigger:** "are we following our own rules?" **Gap filled:** Overlaps with code-reviewer but scoped differently. Code-reviewer evaluates individual PRs; The Emperor evaluates systemic compliance across the whole project. Checks ADRs, CONTRIBUTING.md, architectural decision records, and stated conventions. **Possible modes:** - Convention audit (are naming patterns, file structures consistent?) - ADR compliance (are architectural decisions being followed?) - Boundary check (are module boundaries respected?) - Drift detection (where has the codebase diverged from stated standards?) --- ## Overlap Analysis | Skill | Overlaps With | Distinction | |-------|--------------|-------------| | The Fool | Common Ground, Code Reviewer | Multi-mode critical reasoning vs. assumption surfacing vs. code-level review | | The Hermit | Spec Miner, Debugging Wizard | Understanding systems vs. extracting specs vs. finding bugs | | The Tower | Legacy Modernizer | Clean break rebuild vs. incremental migration | | The Wheel of Fortune | Architecture Designer | Unknown futures vs. known trade-offs | | The Magician | Feature Forge | Feasibility proof vs. requirements definition | | The High Priestess | Code Reviewer | Unnamed intuitions vs. known standards | | The Star | Feature Forge | Alignment check vs. initial specification | | Death | Legacy Modernizer | Graceful ending vs. transformation | | The Emperor | Code Reviewer | Systemic compliance vs. individual PR review | **Strongest unique concepts** (no significant overlap): The Hermit, The Wheel of Fortune, The High Priestess, The Star **Interesting but overlapping** (need clear boundary with existing skills): The Tower, Death, The Emperor, The Magician --- ## File: docs/skill-ideas/the-fool.md # Plan: `the-fool` Skill ## Summary Create a domain-agnostic critical reasoning skill with 5 modes, rooted in the archetype of the Fool — the one who speaks truth to power. Uses `AskUserQuestions` for mode selection. Invoked organically mid-conversation with "play the fool" as mandatory trigger. ## File Structure ``` skills/the-fool/ SKILL.md (~95 lines) references/ socratic-questioning.md (~150 lines) dialectic-synthesis.md (~150 lines) pre-mortem-analysis.md (~200 lines) red-team-adversarial.md (~150 lines) evidence-audit.md (~150 lines) mode-selection-guide.md (~100 lines) ``` ## SKILL.md Design ### Frontmatter ```yaml --- name: the-fool description: Use when challenging ideas, plans, decisions, or proposals using structured critical reasoning. Invoke to play the fool, devil's advocate, pre-mortem, red team, or evidence audit. triggers: - play the fool - devil's advocate - challenge this - stress test - poke holes - what could go wrong - red team - pre-mortem - test my assumptions role: expert scope: review output-format: report --- ``` ### Role Definition The Fool — the court jester who alone could speak truth to the king. Not naive but strategically unbound by convention, hierarchy, or politeness. Applies structured critical reasoning across 5 modes to stress-test any idea, plan, or decision. ### When to Use - Stress-testing a plan, architecture, or strategy before committing - Challenging technology, vendor, or approach choices - Evaluating business proposals, value propositions, or strategies - Red-teaming a design before implementation - Auditing whether evidence actually supports a conclusion - Finding blind spots and unstated assumptions ### Core Workflow (5 steps) 1. **Identify (Thesis)** — Extract the user's position from conversation context. Restate it as a steelmanned thesis for confirmation. 2. **Select (Method)** — Use `AskUserQuestions` to let the user choose a reasoning mode, or auto-recommend based on context signals. 3. **Challenge (Antithesis)** — Apply the selected mode's method. Load the corresponding reference file for deep guidance. 4. **Engage (Dialogue)** — Present findings. Ask the user to respond to the strongest 2-3 points before proceeding. 5. **Synthesize (Resolution)** — Integrate insights into a strengthened position. Offer to run a second pass with a different mode. ### 5 Reasoning Modes | Mode | Method | Output | |------|--------|--------| | Expose My Assumptions | Socratic questioning | Probing questions grouped by theme | | Argue the Other Side | Hegelian dialectic + steel manning | Counter-argument and synthesis proposal | | Find the Failure Modes | Pre-mortem + second-order thinking | Ranked failure narratives with mitigations | | Attack This | Red teaming | Adversary profile, attack vectors, defenses | | Test the Evidence | Falsificationism + evidence weighting | Claims audited with falsification criteria | ### AskUserQuestions Integration **Mode Selection Question:** ``` Header: "Challenge Mode" Question: "How should I challenge this?" Options: 1. "Expose my assumptions" — Ask me the hard questions I haven't asked myself 2. "Argue the other side" — Build the strongest counter-argument and drive toward synthesis 3. "Find the failure modes" — Assume this fails and tell me why 4. "Attack this" — Think like an adversary looking for weaknesses 5. "You choose" — Recommend the best approach based on context ``` If "You choose" is selected, skill analyzes context signals and recommends 1-2 modes with rationale, then confirms with a follow-up AskUserQuestions. ### Reference Routing Table | Topic | Reference | Load When | |-------|-----------|-----------| | Socratic questioning | `references/socratic-questioning.md` | "Expose my assumptions" mode selected | | Dialectic & synthesis | `references/dialectic-synthesis.md` | "Argue the other side" mode selected | | Pre-mortem analysis | `references/pre-mortem-analysis.md` | "Find the failure modes" mode selected | | Red team adversarial | `references/red-team-adversarial.md` | "Attack this" mode selected | | Evidence audit | `references/evidence-audit.md` | "Test the evidence" mode selected | | Mode selection guide | `references/mode-selection-guide.md` | "You choose" selected, or skill needs to auto-recommend | ### Constraints **MUST DO:** - Steelman the thesis before challenging it (restate in strongest form) - Use `AskUserQuestions` for mode selection — never assume which mode - Ground challenges in specific, concrete reasoning (not vague "what ifs") - Maintain intellectual honesty — concede points that hold up - Drive toward synthesis or actionable output (never leave the user with just objections) - Adapt challenge depth to the domain and stakes - Limit challenges to 3-5 strongest points (depth over breadth) - Ask user to engage before synthesizing **MUST NOT DO:** - Strawman the user's position - Generate challenges for the sake of disagreement - Be nihilistic or purely destructive - Stack minor objections to create false impression of weakness - Skip synthesis (never leave the user with just a pile of problems) - Override domain expertise with generic skepticism - Output mode selection as plain text when `AskUserQuestions` can provide structured options ### Related Skills - **Common Ground** — Surface hidden assumptions (use *before* the-fool) - **Architecture Designer** — Document refined decisions as ADRs (use *after* the-fool) - **Code Reviewer** — Structured critique of implementations (tactical counterpart) - **Feature Forge** — Requirements elicitation (challenge specs *after* forging) ## Reference File Designs ### 1. `references/socratic-questioning.md` (~150 lines) Structured question frameworks for exposing assumptions: - Question categories: definitional, evidential, logical, perspective-shifting, consequential - Domain-adapted question banks (technical, business, strategic) - Detection signals for unstated assumptions ("obviously", "everyone knows", "it just makes sense") - Output template: Assumption Inventory + Probing Questions grouped by theme + Suggested Experiments ### 2. `references/dialectic-synthesis.md` (~150 lines) Hegelian dialectic with steel manning: - How to construct a proper antithesis (not a strawman) - Steel manning technique: strengthen the opposing position before arguing it - Reductio ad absurdum as a supporting technique - Synthesis patterns: conditional, scope partitioning, temporal, risk mitigation, hybrid extraction - Synthesis quality checklist and anti-patterns - Confidence assessment: HIGH / MEDIUM / LOW / PIVOT - Output template: Thesis Restated + Antithesis Argued + Synthesis Proposed ### 3. `references/pre-mortem-analysis.md` (~200 lines) Pre-mortem with second-order thinking: - How to run a pre-mortem (assume failure, explain why) - Failure narrative construction (specific > generic) - Second-order consequence chains (first → second → third order effects) - Inversion technique ("what guarantees failure?") - Domain-specific failure patterns: technical (scaling, integration, migration), business (adoption, competition, timing), process (timeline, dependencies, stakeholders) - Output template: Failure Narratives (ranked) + Early Warning Signs + Mitigations ### 4. `references/red-team-adversarial.md` (~150 lines) Adversarial thinking and red teaming: - Adversary persona construction (competitor, attacker, disgruntled user, regulator) - Attack vector identification by domain - Perverse incentive detection ("how will people game this?") - Competitive response analysis - Output template: Adversary Profile + Attack Vectors (ranked by likelihood x impact) + Defenses ### 5. `references/evidence-audit.md` (~150 lines) Falsificationism and evidence quality: - Popper's key question: "What would disprove this?" - Claim extraction from proposals - Falsification criteria design - Evidence quality assessment (sample size, representativeness, recency, relevance) - Cognitive biases in evidence evaluation (confirmation, survivorship, anchoring, availability) - Competing explanations (abductive reasoning) - Output template: Claims Extracted + Falsification Criteria + Evidence Quality + Alternative Explanations ### 6. `references/mode-selection-guide.md` (~100 lines) Context signals for auto-recommending modes: - Signal-to-mode mapping table (user phrases → recommended mode) - Decision type mapping (trade-offs → dialectic, execution plans → pre-mortem, etc.) - Domain mapping (security → red team, data claims → evidence audit, etc.) - Multi-mode sequencing recommendations (e.g., "Socratic first, then dialectic") ## Updates to Existing Files ### SKILLS_GUIDE.md - Add to **Workflow** category (or new **Critical Thinking** category): `The Fool — Challenge ideas and decisions with 5 structured reasoning modes` - Add **Critical Thinking** decision tree: - Surface Assumptions → Common Ground - Challenge Decisions → The Fool - Evaluate Code → Code Reviewer - Audit Security → Security Reviewer - Add **Decision Validation** workflow: 1. Common Ground (surface assumptions) 2. The Fool (stress-test the decision) 3. Architecture Designer (document refined decision) ## Implementation Order 1. Create `skills/the-fool/SKILL.md` 2. Create `skills/the-fool/references/mode-selection-guide.md` 3. Create `skills/the-fool/references/socratic-questioning.md` 4. Create `skills/the-fool/references/dialectic-synthesis.md` 5. Create `skills/the-fool/references/pre-mortem-analysis.md` 6. Create `skills/the-fool/references/red-team-adversarial.md` 7. Create `skills/the-fool/references/evidence-audit.md` 8. Update `SKILLS_GUIDE.md` with new skill entry ## Verification 1. `python scripts/validate-skills.py --skill the-fool` — verify YAML, description format, references 2. `python scripts/update-docs.py --check` — verify counts are in sync 3. Manually verify trigger phrases match natural invocation patterns 4. Review each reference file stays within 100-600 line bounds ## Key Files to Reference During Implementation - `skills/feature-forge/SKILL.md` — AskUserQuestions integration pattern - `skills/feature-forge/references/interview-questions.md` — Structured question flow examples - `skills/code-reviewer/SKILL.md` — Review-scope skill with routing table - `commands/common-ground.md` — Interactive multi-phase dialogue pattern - `SKILLS_GUIDE.md` — Category placement and decision tree format --- ## File: docs/workflow/common-ground.md # common-ground Surface and validate Claude's hidden assumptions about the project for user confirmation. Invocable on-demand at any point in the workflow. --- ## Overview Claude often operates on assumptions about project context, technology choices, coding standards, and user preferences. This utility command surfaces those assumptions for explicit validation. It scans configuration files, reviews conversation context, classifies assumptions by type and confidence tier (OPEN, WORKING, ESTABLISHED), and presents them for user review via an interactive two-phase flow. Assumptions are persisted to a ground file for future reference. Optional modes include read-only listing (`--list`), quick validation (`--check`), and reasoning graph generation (`--graph`). ## Inputs | Name | Type | Required | Description | |------|------|----------|-------------| | `list` | flag | no | Read-only view of all tracked assumptions | | `check` | flag | no | Quick validation of current assumptions | | `graph` | flag | no | Generate mermaid diagram of reasoning structure | ## Outputs | Name | Type | Path | Description | |------|------|------|-------------| | `ground-file` | file | `~/.claude/common-ground/{project-id}/COMMON-GROUND.md` | Human-readable assumptions organized by confidence tier | | `ground-index` | file | `~/.claude/common-ground/{project-id}/ground.index.json` | Machine-readable assumption index | ## Prerequisites - Access to the project codebase (for configuration scanning) - No external tooling required ## Usage Can be invoked at any point during the workflow — during intake, before planning, mid-execution, or whenever assumptions are building up. There is no prescribed moment; use judgment. --- ## File: docs/workflow/discovery-approve.md # discovery:approve Review synthesis findings, resolve blocking decisions, and create implementation tickets in the ticketing system. --- ## Overview The agent fetches the synthesis document, extracts the proposed tickets JSON, and walks through any unresolved blocking decisions interactively. After all decisions are resolved, it presents the full ticket list for review and editing (add, remove, modify). Upon approval, it creates tickets in Jira under the target epics with full descriptions, acceptance criteria, and discovery traceability links. The synthesis document is updated with approval status and created ticket keys. ## Inputs | Name | Type | Required | Description | |------|------|----------|-------------| | `synthesis-url` | url | yes | Confluence URL of the synthesis document to approve | | `decisions` | list[string] | no | Pre-resolved blocking decisions (e.g., `--decision=D1:B --decision=D2:Y`) | ## Outputs | Name | Type | Description | |------|------|-------------| | `created-tickets` | tickets | Jira tickets created in target implementation epics, linked to discovery epic, with full descriptions and acceptance criteria | ## Prerequisites - Synthesis document created via `discovery:synthesize` - Jira and Confluence access configured ## Next Steps After tickets are created, proceed to `planning:epic-plan` to create the stakeholder-readable overview for the target implementation epic. --- ## File: docs/workflow/discovery-create.md # discovery:create Create a structured discovery workspace with research questions, hypotheses, and a research plan for a given topic. --- ## Overview Given an epic key, the agent fetches the epic and its linked tickets, extracts explicit and implicit questions, categorizes them by theme (customer discovery, technical feasibility, business viability, scope boundaries), and identifies appropriate research methods. The output is a published Confluence discovery document that structures the human research phase. ## Inputs | Name | Type | Required | Description | |------|------|----------|-------------| | `epic-key` | string | yes | Jira epic key for the discovery epic (e.g., CC-60) | ## Outputs | Name | Type | Path | Description | |------|------|------|-------------| | `discovery-document` | url | `/epics/Discovery/{epic-key}/` | Confluence page with hypothesis map, research questions matrix, dependencies, research plan, decision framework, and risk register | ## Prerequisites - Epic exists in Jira with linked tickets - Jira and Confluence access configured ## Next Steps After the discovery document is created, humans conduct research (interviews, spikes, competitive analysis). When research is complete, run `discovery:synthesize` with the discovery document URL and any additional research artifact URLs. --- ## File: docs/workflow/discovery-phase.md # Discovery Phase Optional research phase triggered when `feature-forge` identifies unknowns that require human investigation before planning can proceed. --- ## Purpose Not every feature needs discovery. When the feature-forge interview surfaces questions that cannot be answered from existing knowledge — user interviews needed, competitive analysis required, technical spikes pending — those unknowns route here. Discovery provides structure for research and converts findings into actionable epics and tickets. ## Commands | Order | Command | Summary | |-------|---------|---------| | 1 | `discovery:create` | Create a structured discovery workspace with research questions and hypotheses | | 2 | `discovery:synthesize` | Consolidate research artifacts into findings, recommendations, and proposed tickets | | 3 | `discovery:approve` | Resolve blocking decisions and create tickets in the ticketing system | Between steps 1 and 2, humans conduct the actual research: user interviews, technical spikes, competitive analysis, design sprints. ## Outputs - **Discovery document** — Research questions, hypotheses, research plan - **Synthesis document** — Consolidated findings, recommendations, proposed tickets with blocking decisions - **Tickets** — Epics and tickets created in the ticketing system, grounded in research ## Prerequisites - Feature-forge spec with Discovery Recommendation section (recommended) - Ticketing system access (Jira) - Documentation system access (Confluence) ## External Skills - **feature-forge** — Produces the spec that identifies unknowns triggering discovery ## Next Steps After discovery, proceed to the [Planning Phase](planning-phase.md) to create the epic plan and implementation plan from the created tickets. --- ## File: docs/workflow/discovery-synthesize.md # discovery:synthesize Consolidate research artifacts from multiple sources into actionable findings, recommendations, and proposed tickets. --- ## Overview The agent fetches all provided source documents (discovery docs, interview summaries, spike reports, competitive analyses), performs cross-source analysis to identify themes and contradictions, generates feature recommendations mapped to target epics, and produces a comprehensive synthesis document. The synthesis includes a machine-readable proposed tickets section (JSON) that the approval command consumes. ## Inputs | Name | Type | Required | Description | |------|------|----------|-------------| | `source-urls` | list[url] | yes | One or more Confluence document URLs to synthesize | | `target` | string | no | Target implementation epic key (e.g., `--target=CC-62`). Auto-detected from sources if omitted. | ## Outputs | Name | Type | Path | Description | |------|------|------|-------------| | `synthesis-document` | url | `/epics/Discovery/{discovery-epic-key}/Synthesis/` | Confluence page with consolidated findings, validated/invalidated hypotheses, recommendations by epic, blocking decisions, and proposed tickets JSON | ## Prerequisites - Discovery document created via `discovery:create` - Human research completed with artifacts accessible via URL - Jira and Confluence access configured ## Next Steps Review the synthesis document. When ready, run `discovery:approve` with the synthesis URL to resolve blocking decisions and create tickets in the ticketing system. ## 2. Official Technical Reference & Guides (Jeffallan/Jeffallan.github.io) ## File: README.md # Astro Starter Kit: Minimal ```sh npm create astro@latest -- --template minimal ``` > 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! ## 🚀 Project Structure Inside of your Astro project, you'll see the following folders and files: ```text / ├── public/ ├── src/ │ └── pages/ │ └── index.astro └── package.json ``` Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components. Any static assets, like images, can be placed in the `public/` directory. ## 🧞 Commands All commands are run from the root of the project, from a terminal: | Command | Action | | :------------------------ | :----------------------------------------------- | | `npm install` | Installs dependencies | | `npm run dev` | Starts local dev server at `localhost:4321` | | `npm run build` | Build your production site to `./dist/` | | `npm run preview` | Preview your build locally, before deploying | | `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | | `npm run astro -- --help` | Get help using the Astro CLI | ## 👀 Want to learn more? Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). --- ## File: package.json { "name": "jeffallan.github.io", "type": "module", "version": "0.0.1", "scripts": { "dev": "astro dev", "build": "astro build", "preview": "astro preview", "astro": "astro" }, "dependencies": { "@astrojs/sitemap": "^3.7.4", "@fontsource/outfit": "^5.3.0", "@fontsource/source-sans-3": "^5.3.1", "@iconify-json/simple-icons": "^1.2.101", "@jdevalk/astro-seo-graph": "^2.2.0", "astro": "^7.4.2", "astro-icon": "^1.2.0", "astro-og-canvas": "^0.13.2" } } --- ## File: tsconfig.json { "extends": "astro/tsconfigs/strict", "include": [".astro/types.d.ts", "**/*"], "exclude": ["dist"] } --- ## File: .copier-answers.yml # Changes here will be overwritten by Copier. Do not edit by hand. _commit: v0.3.0 _src_path: https://github.com/Jeffallan/handbook.git ci_workflows: [] handbook_docs: [] site_dir: . site_pieces: - site-nav - site-style - site-footer - site-contact - site-seo - site-career --- ## File: public/robots.txt User-agent: * Allow: / Sitemap: https://jeffallan.github.io/sitemap-index.xml Sitemap: https://jeffallan.github.io/claude-skills/sitemap-index.xml Sitemap: https://jeffallan.github.io/writing-with-agents/sitemap-index.xml --- ## File: src/components/site-career/career.json { "person": { "id": "https://jeffallan.github.io/#person", "name": "Jeff Smolinski", "title": "Full-Stack Engineer | Security Engineer", "url": "https://jeffallan.github.io/", "github": "https://github.com/Jeffallan", "bios": { "one_liner": "Principal Consultant at Synergetic Solutions. We build and stress test systems composed of people, processes, and technology resulting in fewer sales objections.", "short": "Jeff Smolinski is Principal Consultant at Synergetic Solutions, where he builds and secures software and data systems for organizations that handle sensitive data. He led an employee benefit plan audit platform from MVP to $1M ARR in its first year, with a SOC 2 program certified in four months, and has helped clients win five Nebraska Innovation Grants totaling more than $375,000. A security researcher with two disclosed CVEs and peer-reviewed research, he holds an MS in Cybersecurity from the University of Nebraska Omaha. His open-source projects have passed 500,000 installs and downloads.", "long": [ "Jeff Smolinski is Principal Consultant at Synergetic Solutions, where he builds and secures software and data systems for organizations that handle sensitive data. He holds an MS in Cybersecurity (Cyber Operations) from the University of Nebraska Omaha.", "As a security researcher, Jeff found and disclosed two cross-site scripting vulnerabilities in the Unicorn framework for Django (CVE-2021-42053 and CVE-2021-42134), which affected 249 repositories. He co-authored peer-reviewed research on LLVM fingerprinting, presented at the International Conference on Cyber Warfare and Security in 2022, and designed a secure audio DRM module for MITRE's 2020 Embedded Capture the Flag.", "In client work, he led an employee benefit plan audit platform from MVP to $1M ARR in its first year, building a SOC 2 program that reached certification in four months and sitting on its governance committee. He served as CTO and board member of a scheduling platform, built data pipelines and a public hospital directory for a hospital capacity planning company, and has helped clients win five Nebraska Innovation Grants totaling more than $375,000.", "At Synergetic he built the Trust Center Directory, which tracks the public compliance footprint of 9,300+ organizations, and a weekly agentic pipeline that turns real security incidents into tabletop exercises. His open-source work, including claude-skills, a library of 67 Agent Skills for Claude, has passed 500,000 installs and downloads.", "His core competencies are application security, threat modeling, secure code review, reverse engineering, GRC programs (SOC 2, HIPAA, FERPA), data engineering and agentic software delivery." ] }, "knows_about": [ "Information security", "Application security", "Governance, risk and compliance", "Vulnerability research", "Incident response", "Disaster recovery", "Physical security", "SecDevOps", "Reverse engineering", "Software engineering", "Data engineering", "Cloud computing", "Technical due diligence", "AI-assisted software development" ], "skills": [ { "group": "Languages", "items": [ "Python", "JavaScript", "TypeScript", "Go" ] }, { "group": "Frameworks", "items": [ "Django", "Django REST Framework", "Vue.js", "React", "React Native", "Next.js", "Astro" ] }, { "group": "Data", "items": [ "data engineering", "PostgreSQL", "Neo4j", "Firebase", "Google BigQuery", "DuckDB", "Parquet", "GeoPandas", "ETL pipelines", "data lakes" ] }, { "group": "Cloud & DevOps", "items": [ "AWS", "GCP", "Azure", "Docker", "CI/CD" ] }, { "group": "Security & compliance", "items": [ "security engineering", "application security", "cloud security", "threat modeling", "reverse engineering", "security policy", "secure code review", "vulnerability research", "technical due diligence", "SOC 2", "HIPAA", "FERPA", "GRC" ] }, { "group": "Process & leadership", "items": [ "Agile / Scrum", "SDLC", "technical leadership", "team building" ] }, { "group": "AI", "items": [ "Claude (Claude Code", "Claude API)", "Agent Skills", "agentic SDLC workflows" ] } ], "experience": [ { "org": "synergetic", "employer": "Synergetic Holdings, LLC (Synergetic Solutions)", "position": "Principal Consultant", "start": "2018", "bullets": [ "Providing greenfield and legacy development as a service for client web apps and cloud infrastructure informed by security requirements, threat modeling, and secure code review.", "Conducting technical due diligence to evaluate security compliance readiness, guide clients through compliance efforts, and deliver technical assessments to inform funding decisions.", "Driving enterprise customer acquisition by architecting and implementing Governance Risk Compliance programs and authentication infrastructure that eliminate technical barriers in enterprise sales." ] } ], "vulnerabilities": [ { "id": "CVE-2021-42053", "url": "https://nvd.nist.gov/vuln/detail/CVE-2021-42053", "summary": "Cross-site scripting in the Unicorn framework for Django (through 0.35.3)", "severity": "5.4 Medium (CVSS 3.1)", "impact": "1 library, 6 packages and 249 repositories impacted" }, { "id": "CVE-2021-42134", "url": "https://nvd.nist.gov/vuln/detail/CVE-2021-42134", "summary": "Cross-site scripting in the Unicorn framework for Django (before 0.36.1), from an incomplete fix for CVE-2021-42053", "severity": "6.1 Medium (CVSS 3.1)", "impact": "1 library, 6 packages and 249 repositories impacted" } ], "competitions": [ { "name": "MITRE Embedded Capture the Flag (eCTF), 2020", "url": "https://ectf.mitre.org/past-competitions/", "text": "Designed a secure audio DRM module for a next-generation multimedia player on the Digilent Cora Z7." } ], "publications": [ { "citation": "W. Mahoney, P. Sigillito, J. Smolinski, T. McDonald, and G. Grispos, \"Analyzing the Performance of Block-Splitting in LLVM Fingerprinting,\" International Conference on Cyber Warfare and Security, vol. 17, no. 1. Academic Conferences International Ltd, pp. 176–184, Mar. 02, 2022.", "doi": "10.34190/iccws.17.1.39", "url": "https://doi.org/10.34190/iccws.17.1.39" } ], "open_source": [ { "name": "claude-skills", "url": "https://github.com/Jeffallan/claude-skills", "count": "441K+ installs", "text": "67 specialized skills for full-stack developers." }, { "name": "writing-with-agents", "url": "https://github.com/Jeffallan/writing-with-agents", "count": "177 installs", "text": "A Claude Code plugin for writing with AI, built on Betty Flowers' Madman-Architect-Carpenter-Judge method." }, { "name": "badfiles", "url": "https://pypi.org/project/badfiles", "count": "39K+ downloads", "text": "A malicious file detection engine written with Python and Yara." }, { "name": "fitness-tools", "url": "https://pypi.org/project/fitness-tools", "count": "21K+ downloads", "text": "A library to help personal trainers optimize client training and macronutrient requirements." } ], "education": [ { "degree": "MS Cybersecurity (Cyber Operations)", "school": "University of Nebraska Omaha", "location": "Omaha, NE", "gpa": "4.0" }, { "degree": "BA General Studies", "school": "Adams State University", "location": "Alamosa, CO", "gpa": "4.0" } ], "recognition": [ { "name": "Certificate of Recognition, Omaha Chamber of Commerce (2017)", "text": "For teaching 20 small business owners WordPress development." } ] }, "organization": { "id": "synergetic", "legal_name": "Synergetic Holdings, LLC", "name": "Synergetic Solutions", "url": "https://synergetic.solutions", "naics": [ "541512", "541511", "541690" ], "services": [ "AI Strategy & Implementation", "Software, Security & Data Engineering", "Incident Response & Remediation", "GRC Strategy & Implementation", "Technical Due Diligence", "SDLC Strategy & Implementation", "Fractional CTO & CISO Services" ], "competencies": [ "We build and secure the software, data and governance processes our clients' core operations depend on", "We bring experience from fintech, healthtech, public safety, and embedded systems" ], "differentiators": [ "Our principal has served as CTO and board member of a client company and has led client GRC programs in a fractional CISO role", "We take a collaborative, proactive approach when solving our clients' challenges, resulting in practical solutions ensuring both client satisfaction and business continuity", "Agentic SDLC delivery: one developer averaging 80+ tickets and 12 merged pull requests a week per project, with every phase leaving a reviewable artifact", "Legacy codebase intake: preparing legacy codebases for agentic development with a repeatable procedure including proper documentation, unit tests, end-to-end tests, and security tests" ], "industries": [ "FinTech", "Media & Entertainment", "HealthTech", "Public Safety & Security", "InsuranceTech" ], "statements": [ { "text": "Implementing a security compliance program that achieved SOC 2 certification in 4 months" }, { "text": "Architecting and maintaining large-scale datasets supporting multi-million dollar business decisions" }, { "text": "Helping clients win $375K+ across 5 Nebraska Innovation Grant awards, one recipient scaling from MVP to $1M ARR in a year" }, { "text": "Discovering and responsibly disclosing software vulnerabilities" }, { "text": "Leading incident response and forensic investigations for production security incidents" }, { "text": "Co-authoring peer-reviewed research published at the International Conference on Cyber Warfare and Security" }, { "text": "Conducting technical due diligence to validate product ownership and investment readiness" }, { "text": "Designing and implementing SDLC frameworks for 5+ organizations, reducing time-to-deployment through CI/CD automation and Agile adoption" }, { "text": "Developing custom ETL pipelines across healthcare, fintech, and security sectors, establishing the data foundations required for AI and machine learning adoption" }, { "text": "Shipping multiple mobile applications from concept to app store deployment within 4 months" }, { "text": "Building and publishing a compliance-signal directory covering 9,300+ organizations" }, { "text": "Publishing a library of incident response and disaster recovery tabletop scenarios drawn from current incidents" } ] }, "clients": [ { "id": "client-1", "description": "Employee benefit plan audit platform", "industry": "FinTech", "role": "Consultant", "status": "past", "technologies": [ "Vue.js", "Django REST Framework", "PostgreSQL", "Pandas", "openpyxl", "Microsoft Azure" ], "bullets": [ { "text": "Built an MVP that gained traction within 3 months." }, { "text": "Introduced an Agile workflow that raised team efficiency by 20%." }, { "text": "Hired and mentored engineers, growing the engineering team fourfold." }, { "text": "Wrote a custom ETL pipeline for 401(k) and payroll data from 20+ sources, saving auditors about 30 hours per project." }, { "text": "Set up CI/CD, doubling delivery speed." }, { "text": "Led development of the platform, which reached $1M ARR in its first year." }, { "text": "Implemented security controls and a SOC 2 program, opening enterprise sales and raising company value sixfold." }, { "text": "Led the GRC program and sat on the governance committee, filling the fractional CISO role." } ], "resume": [ 5, 6, 7, 3 ] }, { "id": "client-2", "description": "Sports team communication platform", "industry": "Media & Entertainment", "role": "Consultant", "status": "current", "technologies": [ "React", "TypeScript", "React Native", "PostgreSQL", "GCP", "Firebase", "Terraform", "Claude Code" ], "bullets": [ { "text": "Helped the client win $75,000 in grant funding for prototype development." }, { "text": "Shipped the mobile app to both app stores within 4 months." }, { "text": "Implemented an agentic SDLC with technical discovery, requirements engineering, test-first delivery, security review and acceptance testing." }, { "text": "Found and fixed security vulnerabilities inherited from a legacy Replit codebase." }, { "text": "Building a GRC program for SOC 2 and FERPA compliance.", "status": "in-progress" }, { "text": "Product-market fit validation, go-to-market strategy and a custom advertising network for monetization.", "status": "in-progress" }, { "text": "Averaged 80+ tickets and 12 merged pull requests a week using an agentic SDLC." } ], "resume": [ 6, 1, 3 ] }, { "id": "client-3", "description": "Hospital capacity planning application", "industry": "HealthTech", "role": "Consultant", "status": "current", "technologies": [ "React", "Go", "GCP", "Firebase", "Google BigQuery", "Claude Code" ], "bullets": [ { "text": "Improved the UX in React, raising customer adoption by 50%." }, { "text": "Built data collection and matching methods that save about 30 minutes of manual work per data source." }, { "text": "Extended the ETL pipeline to ingest large CMS (Centers for Medicare & Medicaid Services) datasets." }, { "text": "Curated and restructured a legacy data lake, laying the groundwork for AI and machine learning." }, { "text": "Tied Stripe subscription status to role-based access control for billing and permissions." }, { "text": "Designed multi-tenant support so organizations can manage employee accounts and share project data." }, { "text": "Built public hospital directory from CMS cost report data (HCRIS), using an agentic SDLC workflow." } ], "resume": [ 0, 1, 6 ] }, { "id": "client-4", "description": "Physical security services company", "industry": "Public Safety & Security", "role": "Consultant", "status": "current", "technologies": [ "Python", "GeoPandas", "TypeScript", "React", "PostgreSQL", "Private VPS" ], "bullets": [ { "text": "Aggregated, cleaned, geotagged and geofenced Omaha, NE police incident data to strengthen the company's threat intelligence and staffing decisions." }, { "text": "Modernized client camera systems, laying the foundation for Flock Safety municipal camera network integration." }, { "text": "Designed a scheduling, billing and communication system that sped up client communication and halved administrative overhead." } ], "resume": [ 0, 1, 2 ] }, { "id": "client-5", "description": "Scheduling platform connecting entertainers with retirement communities", "industry": "Media & Entertainment", "role": "CTO and board member", "status": "concluded", "technologies": [ "Next.js", "Neo4j", "Private VPS", "Claude Code" ], "bullets": [ { "text": "Served as CTO and board member, guiding technical implementation and market strategy." }, { "text": "Designed infrastructure for 20% annual user growth, with network activity doubling each year." }, { "text": "Developed a data cleaning and migration strategy for the Neo4j graph database." }, { "text": "Implemented an agentic SDLC with technical discovery, requirements engineering, test-first delivery, security review and acceptance testing." }, { "text": "Designed an SDK and v2 API for wider adoption in the scheduling space, using Neo4j's graph features for real-time availability and location intelligence." } ], "resume": [ 0, 1, 4 ] } ], "products": [ { "id": "trust-center-directory", "order": 1, "name": "Trust Center Directory", "owner": "synergetic", "url": "https://synergetic.solutions/resources/trust-center-directory/", "dataset": "https://github.com/synergetic-solutions/trust-index-data", "status": "current", "technologies": [ "Python", "DuckDB", "Common Crawl", "Claude API", "Parquet", "Google Cloud Storage", "Google BigQuery" ], "description": "A public directory of organizations with a public compliance footprint.", "bullets": [ { "text": "Built and run a public directory of 9,300+ organizations with a public compliance footprint, refreshed monthly." }, { "text": "Designed the data pipeline: Common Crawl via DuckDB, DNS discovery, parsers for four trust-center platforms, Claude-based classification, and Parquet snapshots in GCS and BigQuery." }, { "text": "Published an open-core dataset (CC BY 4.0) with versioned releases and evidence-checked community corrections." } ] }, { "id": "tabletop-scenario-library", "order": 2, "name": "Tabletop Scenario Library", "owner": "synergetic", "url": "https://synergetic.solutions/resources/tabletop-scenarios/", "status": "current", "technologies": [ "Claude Code", "Agent Skills", "GitHub Actions", "Astro", "Cloudflare Pages" ], "description": "Incident response and disaster recovery tabletop exercises drawn from current incidents.", "bullets": [ { "text": "Built a weekly agentic content pipeline turning real security incidents into tabletop exercise scenarios: scheduled Claude intake with review and greenlight steps, lint and rubric checks enforced in code, and automated publishing and social export." } ] } ] } --- ## File: src/components/site-footer/profile.json { "_icons": "Simple Icons (https://simpleicons.org), CC0-1.0; 24x24 viewBox", "name": "Jeff Smolinski", "url": "https://github.com/Jeffallan", "role": "Principal Consultant", "org": { "name": "Synergetic Solutions", "url": "https://synergetic.solutions" }, "profiles": [ { "name": "GitHub", "url": "https://github.com/Jeffallan", "path": "M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12" }, { "name": "LinkedIn", "url": "https://linkedin.com/in/jeff-smolinski", "path": "M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037c-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85c3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.06 2.06 0 0 1-2.063-2.065a2.064 2.064 0 1 1 2.063 2.065m1.782 13.019H3.555V9h3.564zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0z" }, { "name": "X", "url": "https://x.com/j3ffallan", "path": "M14.234 10.162L22.977 0h-2.072l-7.591 8.824L7.251 0H.258l9.168 13.343L.258 24H2.33l8.016-9.318L16.749 24h6.993zm-2.837 3.299l-.929-1.329L3.076 1.56h3.182l5.965 8.532l.929 1.329l7.754 11.09h-3.182z" }, { "name": "Bluesky", "url": "https://bsky.app/profile/jeffallan.bsky.social", "path": "M5.202 2.857C7.954 4.922 10.913 9.11 12 11.358c1.087-2.247 4.046-6.436 6.798-8.501C20.783 1.366 24 .213 24 3.883c0 .732-.42 6.156-.667 7.037c-.856 3.061-3.978 3.842-6.755 3.37c4.854.826 6.089 3.562 3.422 6.299c-5.065 5.196-7.28-1.304-7.847-2.97c-.104-.305-.152-.448-.153-.327c0-.121-.05.022-.153.327c-.568 1.666-2.782 8.166-7.847 2.97c-2.667-2.737-1.432-5.473 3.422-6.3c-2.777.473-5.899-.308-6.755-3.369C.42 10.04 0 4.615 0 3.883c0-3.67 3.217-2.517 5.202-1.026" }, { "name": "Hacker News", "url": "https://news.ycombinator.com/user?id=Jeffallan", "path": "M0 24V0h24v24zM6.951 5.896l4.112 7.708v5.064h1.583v-4.972l4.148-7.799h-1.749l-2.457 4.875c-.372.745-.688 1.434-.688 1.434s-.297-.708-.651-1.434L8.831 5.896z" } ] } --- ## File: src/components/site-nav/sites.json [ { "name": "About the Author", "url": "https://jeffallan.github.io/", "home": true }, { "name": "Docs: Claude Skills", "url": "https://jeffallan.github.io/claude-skills/" }, { "name": "Docs: Writing With Agents", "url": "https://jeffallan.github.io/writing-with-agents/" }, { "name": "Trust Center Directory", "url": "https://synergetic.solutions/resources/trust-center-directory/" } ] --- ## File: .github/workflows/build.yml # Builds the site on every pull request, so a change (such as a handbook update that moves the # shared site package versions) is checked before it reaches master. Deploying stays in deploy.yml. name: Build on: pull_request: workflow_dispatch: permissions: contents: read jobs: build: name: Build site runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: "24" cache: npm - name: Install dependencies run: npm ci - name: Build with Astro run: npm run build --- ## File: .github/workflows/deploy.yml name: Deploy to GitHub Pages on: push: branches: [master] schedule: # Daily at 6:00 AM Central (11:00 UTC; GitHub cron is UTC-only, so this is 5:00 AM during CST) - cron: "0 11 * * *" workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: "pages" cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: "24" cache: npm - name: Install dependencies run: npm ci - name: Build with Astro run: npm run build env: # Only this build submits changed pages to IndexNow (site-seo) INDEXNOW_SUBMIT: "1" - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: ./dist deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 --- ## File: .github/workflows/handbook-update.yml # Delivered by the handbook (Copier). Opens a PR when a new handbook version is available. # Triggered by the handbook's publish workflow, with a weekly check in case a push is missed. # Needs the handbook GitHub App: variable HANDBOOK_APP_ID and secret HANDBOOK_APP_PRIVATE_KEY. # Until HANDBOOK_APP_ID is set, the job is skipped instead of failing. name: Handbook update on: repository_dispatch: types: [handbook-updated] schedule: - cron: "17 6 * * 1" workflow_dispatch: permissions: contents: read jobs: update: if: vars.HANDBOOK_APP_ID != '' runs-on: ubuntu-latest steps: - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 id: app with: app-id: ${{ vars.HANDBOOK_APP_ID }} private-key: ${{ secrets.HANDBOOK_APP_PRIVATE_KEY }} owner: ${{ github.repository_owner }} repositories: | handbook ${{ github.event.repository.name }} - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: token: ${{ steps.app.outputs.token }} - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: "24" - name: Let git read the private handbook run: git config --global url."https://x-access-token:${{ steps.app.outputs.token }}@github.com/".insteadOf "https://github.com/" - name: Check for a new handbook version id: check run: | uvx copier check-update --output-format json > check.json echo "available=$(jq -r .update_available check.json)" >> "$GITHUB_OUTPUT" echo "version=$(jq -r .latest_version check.json)" >> "$GITHUB_OUTPUT" rm check.json - name: Update from the handbook if: steps.check.outputs.available == 'true' # --trust: the handbook runs personal-sites/versions.mjs to carry the shared site package versions run: uvx copier update --defaults --trust - name: Open the update PR if: steps.check.outputs.available == 'true' uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 with: token: ${{ steps.app.outputs.token }} branch: handbook/update commit-message: "chore: update handbook to v${{ steps.check.outputs.version }}" title: "Update handbook to v${{ steps.check.outputs.version }}" body: | Copier update from the handbook, v${{ steps.check.outputs.version }}. Conflict markers, if any, mark places where a local edit and the handbook changed the same lines.