From 37774aa93778d333e868aca98e2fc8b65118cdcb Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:37:27 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 42 + README.md | 3 + plugin.lock.json | 552 ++++ skills/ln-110-documents-pipeline/SKILL.md | 475 ++++ skills/ln-110-documents-pipeline/diagram.html | 123 + skills/ln-111-root-docs-creator/SKILL.md | 444 ++++ skills/ln-111-root-docs-creator/diagram.html | 109 + .../references/claude_md_template.md | 128 + .../references/docs_root_readme_template.md | 224 ++ .../documentation_standards_template.md | 160 ++ .../references/principles_template.md | 110 + .../references/questions.md | 475 ++++ skills/ln-112-reference-docs-creator/SKILL.md | 325 +++ .../diagram.html | 98 + .../references/questions.md | 119 + .../references/reference_readme_template.md | 63 + skills/ln-113-tasks-docs-creator/SKILL.md | 509 ++++ skills/ln-113-tasks-docs-creator/diagram.html | 123 + .../references/kanban_board_template.md | 170 ++ .../references/questions.md | 274 ++ .../references/tasks_readme_template.md | 541 ++++ skills/ln-114-project-docs-creator/SKILL.md | 457 ++++ .../ln-114-project-docs-creator/diagram.html | 129 + .../guides/automatic_analysis_guide.md | 206 ++ .../references/guides/critical_questions.md | 307 +++ .../references/guides/examples.md | 120 + .../references/guides/template_mappings.md | 285 ++ .../references/guides/troubleshooting.md | 41 + .../references/questions.md | 750 ++++++ .../references/templates/api_spec_template.md | 373 +++ .../templates/architecture_template.md | 271 ++ .../templates/database_schema_template.md | 293 +++ .../templates/design_guidelines_template.md | 351 +++ .../templates/requirements_template.md | 168 ++ .../references/templates/runbook_template.md | 632 +++++ .../templates/tech_stack_template.md | 249 ++ skills/ln-115-presentation-creator/SKILL.md | 785 ++++++ .../ln-115-presentation-creator/diagram.html | 102 + .../presentation_final.html | 2288 +++++++++++++++++ .../references/TEMPLATE_ARCHITECTURE.md | 302 +++ .../references/build-presentation.js | 67 + .../references/mermaid_guidelines.md | 389 +++ .../presentation_readme_template.md | 146 ++ .../references/presentation_template.html | 66 + .../references/scripts.js | 124 + .../references/styles.css | 778 ++++++ .../references/tabs/tab_architecture.html | 177 ++ .../references/tabs/tab_guides.html | 198 ++ .../references/tabs/tab_overview.html | 127 + .../references/tabs/tab_requirements.html | 210 ++ .../references/tabs/tab_roadmap.html | 315 +++ .../references/tabs/tab_technical_spec.html | 364 +++ skills/ln-116-test-docs-creator/SKILL.md | 440 ++++ skills/ln-116-test-docs-creator/diagram.html | 126 + .../references/questions.md | 235 ++ .../references/testing_strategy_template.md | 465 ++++ .../references/tests_readme_template.md | 114 + skills/ln-200-scope-decomposer/SKILL.md | 385 +++ skills/ln-200-scope-decomposer/diagram.html | 151 ++ skills/ln-210-epic-coordinator/SKILL.md | 594 +++++ skills/ln-210-epic-coordinator/diagram.html | 136 + .../references/epic_template_universal.md | 95 + .../references/linear_integration.md | 372 +++ skills/ln-220-story-coordinator/SKILL.md | 456 ++++ skills/ln-220-story-coordinator/diagram.html | 170 ++ .../references/replan_algorithm.md | 506 ++++ skills/ln-221-standards-researcher/SKILL.md | 199 ++ .../ln-221-standards-researcher/diagram.html | 118 + .../references/research_guidelines.md | 190 ++ skills/ln-222-story-creator/SKILL.md | 260 ++ skills/ln-222-story-creator/diagram.html | 97 + .../references/story_template_universal.md | 195 ++ skills/ln-223-story-replanner/SKILL.md | 273 ++ skills/ln-223-story-replanner/diagram.html | 111 + .../references/replan_algorithm_stories.md | 176 ++ skills/ln-300-story-pipeline/SKILL.md | 488 ++++ skills/ln-300-story-pipeline/diagram.html | 133 + .../references/checkpoint_format.md | 13 + skills/ln-310-story-decomposer/SKILL.md | 61 + skills/ln-310-story-decomposer/diagram.html | 79 + skills/ln-311-task-creator/SKILL.md | 69 + skills/ln-311-task-creator/diagram.html | 94 + .../references/refactoring_task_template.md | 515 ++++ .../task_template_implementation.md | 146 ++ .../references/test_task_template.md | 542 ++++ skills/ln-312-task-replanner/SKILL.md | 65 + skills/ln-312-task-replanner/diagram.html | 127 + .../references/replan_algorithm.md | 665 +++++ skills/ln-320-story-validator/SKILL.md | 119 + skills/ln-320-story-validator/diagram.html | 84 + .../references/verification_checklist.md | 457 ++++ skills/ln-321-guide-creator/SKILL.md | 43 + skills/ln-321-guide-creator/diagram.html | 60 + .../references/guide_template.md | 43 + skills/ln-322-adr-creator/SKILL.md | 45 + skills/ln-322-adr-creator/diagram.html | 105 + .../references/adr_template.md | 70 + skills/ln-323-manual-creator/SKILL.md | 43 + skills/ln-323-manual-creator/diagram.html | 203 ++ .../references/manual_template.md | 119 + skills/ln-330-story-executor/SKILL.md | 51 + skills/ln-330-story-executor/diagram.html | 189 ++ skills/ln-331-task-executor/SKILL.md | 46 + skills/ln-331-task-executor/diagram.html | 58 + skills/ln-332-task-reviewer/SKILL.md | 49 + skills/ln-332-task-reviewer/diagram.html | 64 + skills/ln-333-task-rework/SKILL.md | 41 + skills/ln-333-task-rework/diagram.html | 54 + skills/ln-334-test-executor/SKILL.md | 44 + skills/ln-334-test-executor/diagram.html | 64 + skills/ln-340-story-quality-gate/SKILL.md | 53 + skills/ln-340-story-quality-gate/diagram.html | 97 + .../manual_testing_comment_template.md | 444 ++++ .../references/story_review_checklist.md | 394 +++ skills/ln-341-code-quality-checker/SKILL.md | 37 + .../ln-341-code-quality-checker/diagram.html | 209 ++ .../references/architecture_violations.md | 143 ++ .../references/dry_violations.md | 231 ++ .../references/kiss_violations.md | 75 + .../references/yagni_violations.md | 72 + skills/ln-342-regression-checker/SKILL.md | 36 + skills/ln-342-regression-checker/diagram.html | 127 + .../references/pytest_configuration.md | 207 ++ skills/ln-343-manual-tester/SKILL.md | 37 + skills/ln-343-manual-tester/diagram.html | 215 ++ .../references/puppeteer_patterns.md | 357 +++ .../references/test_result_format_v1.md | 264 ++ skills/ln-350-story-test-planner/SKILL.md | 301 +++ skills/ln-350-story-test-planner/diagram.html | 110 + .../references/risk_based_testing_examples.md | 187 ++ .../references/risk_based_testing_guide.md | 492 ++++ 131 files changed, 31137 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/ln-110-documents-pipeline/SKILL.md create mode 100644 skills/ln-110-documents-pipeline/diagram.html create mode 100644 skills/ln-111-root-docs-creator/SKILL.md create mode 100644 skills/ln-111-root-docs-creator/diagram.html create mode 100644 skills/ln-111-root-docs-creator/references/claude_md_template.md create mode 100644 skills/ln-111-root-docs-creator/references/docs_root_readme_template.md create mode 100644 skills/ln-111-root-docs-creator/references/documentation_standards_template.md create mode 100644 skills/ln-111-root-docs-creator/references/principles_template.md create mode 100644 skills/ln-111-root-docs-creator/references/questions.md create mode 100644 skills/ln-112-reference-docs-creator/SKILL.md create mode 100644 skills/ln-112-reference-docs-creator/diagram.html create mode 100644 skills/ln-112-reference-docs-creator/references/questions.md create mode 100644 skills/ln-112-reference-docs-creator/references/reference_readme_template.md create mode 100644 skills/ln-113-tasks-docs-creator/SKILL.md create mode 100644 skills/ln-113-tasks-docs-creator/diagram.html create mode 100644 skills/ln-113-tasks-docs-creator/references/kanban_board_template.md create mode 100644 skills/ln-113-tasks-docs-creator/references/questions.md create mode 100644 skills/ln-113-tasks-docs-creator/references/tasks_readme_template.md create mode 100644 skills/ln-114-project-docs-creator/SKILL.md create mode 100644 skills/ln-114-project-docs-creator/diagram.html create mode 100644 skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md create mode 100644 skills/ln-114-project-docs-creator/references/guides/critical_questions.md create mode 100644 skills/ln-114-project-docs-creator/references/guides/examples.md create mode 100644 skills/ln-114-project-docs-creator/references/guides/template_mappings.md create mode 100644 skills/ln-114-project-docs-creator/references/guides/troubleshooting.md create mode 100644 skills/ln-114-project-docs-creator/references/questions.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/api_spec_template.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/architecture_template.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/database_schema_template.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/design_guidelines_template.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/requirements_template.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/runbook_template.md create mode 100644 skills/ln-114-project-docs-creator/references/templates/tech_stack_template.md create mode 100644 skills/ln-115-presentation-creator/SKILL.md create mode 100644 skills/ln-115-presentation-creator/diagram.html create mode 100644 skills/ln-115-presentation-creator/presentation_final.html create mode 100644 skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md create mode 100644 skills/ln-115-presentation-creator/references/build-presentation.js create mode 100644 skills/ln-115-presentation-creator/references/mermaid_guidelines.md create mode 100644 skills/ln-115-presentation-creator/references/presentation_readme_template.md create mode 100644 skills/ln-115-presentation-creator/references/presentation_template.html create mode 100644 skills/ln-115-presentation-creator/references/scripts.js create mode 100644 skills/ln-115-presentation-creator/references/styles.css create mode 100644 skills/ln-115-presentation-creator/references/tabs/tab_architecture.html create mode 100644 skills/ln-115-presentation-creator/references/tabs/tab_guides.html create mode 100644 skills/ln-115-presentation-creator/references/tabs/tab_overview.html create mode 100644 skills/ln-115-presentation-creator/references/tabs/tab_requirements.html create mode 100644 skills/ln-115-presentation-creator/references/tabs/tab_roadmap.html create mode 100644 skills/ln-115-presentation-creator/references/tabs/tab_technical_spec.html create mode 100644 skills/ln-116-test-docs-creator/SKILL.md create mode 100644 skills/ln-116-test-docs-creator/diagram.html create mode 100644 skills/ln-116-test-docs-creator/references/questions.md create mode 100644 skills/ln-116-test-docs-creator/references/testing_strategy_template.md create mode 100644 skills/ln-116-test-docs-creator/references/tests_readme_template.md create mode 100644 skills/ln-200-scope-decomposer/SKILL.md create mode 100644 skills/ln-200-scope-decomposer/diagram.html create mode 100644 skills/ln-210-epic-coordinator/SKILL.md create mode 100644 skills/ln-210-epic-coordinator/diagram.html create mode 100644 skills/ln-210-epic-coordinator/references/epic_template_universal.md create mode 100644 skills/ln-210-epic-coordinator/references/linear_integration.md create mode 100644 skills/ln-220-story-coordinator/SKILL.md create mode 100644 skills/ln-220-story-coordinator/diagram.html create mode 100644 skills/ln-220-story-coordinator/references/replan_algorithm.md create mode 100644 skills/ln-221-standards-researcher/SKILL.md create mode 100644 skills/ln-221-standards-researcher/diagram.html create mode 100644 skills/ln-221-standards-researcher/references/research_guidelines.md create mode 100644 skills/ln-222-story-creator/SKILL.md create mode 100644 skills/ln-222-story-creator/diagram.html create mode 100644 skills/ln-222-story-creator/references/story_template_universal.md create mode 100644 skills/ln-223-story-replanner/SKILL.md create mode 100644 skills/ln-223-story-replanner/diagram.html create mode 100644 skills/ln-223-story-replanner/references/replan_algorithm_stories.md create mode 100644 skills/ln-300-story-pipeline/SKILL.md create mode 100644 skills/ln-300-story-pipeline/diagram.html create mode 100644 skills/ln-300-story-pipeline/references/checkpoint_format.md create mode 100644 skills/ln-310-story-decomposer/SKILL.md create mode 100644 skills/ln-310-story-decomposer/diagram.html create mode 100644 skills/ln-311-task-creator/SKILL.md create mode 100644 skills/ln-311-task-creator/diagram.html create mode 100644 skills/ln-311-task-creator/references/refactoring_task_template.md create mode 100644 skills/ln-311-task-creator/references/task_template_implementation.md create mode 100644 skills/ln-311-task-creator/references/test_task_template.md create mode 100644 skills/ln-312-task-replanner/SKILL.md create mode 100644 skills/ln-312-task-replanner/diagram.html create mode 100644 skills/ln-312-task-replanner/references/replan_algorithm.md create mode 100644 skills/ln-320-story-validator/SKILL.md create mode 100644 skills/ln-320-story-validator/diagram.html create mode 100644 skills/ln-320-story-validator/references/verification_checklist.md create mode 100644 skills/ln-321-guide-creator/SKILL.md create mode 100644 skills/ln-321-guide-creator/diagram.html create mode 100644 skills/ln-321-guide-creator/references/guide_template.md create mode 100644 skills/ln-322-adr-creator/SKILL.md create mode 100644 skills/ln-322-adr-creator/diagram.html create mode 100644 skills/ln-322-adr-creator/references/adr_template.md create mode 100644 skills/ln-323-manual-creator/SKILL.md create mode 100644 skills/ln-323-manual-creator/diagram.html create mode 100644 skills/ln-323-manual-creator/references/manual_template.md create mode 100644 skills/ln-330-story-executor/SKILL.md create mode 100644 skills/ln-330-story-executor/diagram.html create mode 100644 skills/ln-331-task-executor/SKILL.md create mode 100644 skills/ln-331-task-executor/diagram.html create mode 100644 skills/ln-332-task-reviewer/SKILL.md create mode 100644 skills/ln-332-task-reviewer/diagram.html create mode 100644 skills/ln-333-task-rework/SKILL.md create mode 100644 skills/ln-333-task-rework/diagram.html create mode 100644 skills/ln-334-test-executor/SKILL.md create mode 100644 skills/ln-334-test-executor/diagram.html create mode 100644 skills/ln-340-story-quality-gate/SKILL.md create mode 100644 skills/ln-340-story-quality-gate/diagram.html create mode 100644 skills/ln-340-story-quality-gate/references/manual_testing_comment_template.md create mode 100644 skills/ln-340-story-quality-gate/references/story_review_checklist.md create mode 100644 skills/ln-341-code-quality-checker/SKILL.md create mode 100644 skills/ln-341-code-quality-checker/diagram.html create mode 100644 skills/ln-341-code-quality-checker/references/architecture_violations.md create mode 100644 skills/ln-341-code-quality-checker/references/dry_violations.md create mode 100644 skills/ln-341-code-quality-checker/references/kiss_violations.md create mode 100644 skills/ln-341-code-quality-checker/references/yagni_violations.md create mode 100644 skills/ln-342-regression-checker/SKILL.md create mode 100644 skills/ln-342-regression-checker/diagram.html create mode 100644 skills/ln-342-regression-checker/references/pytest_configuration.md create mode 100644 skills/ln-343-manual-tester/SKILL.md create mode 100644 skills/ln-343-manual-tester/diagram.html create mode 100644 skills/ln-343-manual-tester/references/puppeteer_patterns.md create mode 100644 skills/ln-343-manual-tester/references/test_result_format_v1.md create mode 100644 skills/ln-350-story-test-planner/SKILL.md create mode 100644 skills/ln-350-story-test-planner/diagram.html create mode 100644 skills/ln-350-story-test-planner/references/risk_based_testing_examples.md create mode 100644 skills/ln-350-story-test-planner/references/risk_based_testing_guide.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9439706 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,42 @@ +{ + "name": "full-development-workflow-skills", + "description": "Full development workflow skills: Documentation, Planning, Execution. Requires Linear + Context7 + Ref MCP servers.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Lev Nikolaevich", + "email": "levnikolaevich.com@gmail.com" + }, + "skills": [ + "./skills/ln-110-documents-pipeline", + "./skills/ln-111-root-docs-creator", + "./skills/ln-112-reference-docs-creator", + "./skills/ln-113-tasks-docs-creator", + "./skills/ln-114-project-docs-creator", + "./skills/ln-115-presentation-creator", + "./skills/ln-116-test-docs-creator", + "./skills/ln-200-scope-decomposer", + "./skills/ln-210-epic-coordinator", + "./skills/ln-220-story-coordinator", + "./skills/ln-221-standards-researcher", + "./skills/ln-222-story-creator", + "./skills/ln-223-story-replanner", + "./skills/ln-300-story-pipeline", + "./skills/ln-310-story-decomposer", + "./skills/ln-311-task-creator", + "./skills/ln-312-task-replanner", + "./skills/ln-320-story-validator", + "./skills/ln-321-guide-creator", + "./skills/ln-322-adr-creator", + "./skills/ln-323-manual-creator", + "./skills/ln-330-story-executor", + "./skills/ln-331-task-executor", + "./skills/ln-332-task-reviewer", + "./skills/ln-333-task-rework", + "./skills/ln-334-test-executor", + "./skills/ln-340-story-quality-gate", + "./skills/ln-341-code-quality-checker", + "./skills/ln-342-regression-checker", + "./skills/ln-343-manual-tester", + "./skills/ln-350-story-test-planner" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8e70f04 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# full-development-workflow-skills + +Full development workflow skills: Documentation, Planning, Execution. Requires Linear + Context7 + Ref MCP servers. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..d6f0233 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,552 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:levnikolaevich/claude-code-skills:full-development-workflow-skills", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "54436435045d710680e87f149f5a20b3ec89488f", + "treeHash": "96357b5b5b4867fce6ddd1bc70c98c1662669458a19febd933e137c547778782", + "generatedAt": "2025-11-28T10:20:05.121138Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "full-development-workflow-skills", + "description": "Full development workflow skills: Documentation, Planning, Execution. Requires Linear + Context7 + Ref MCP servers." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "697f695a2654899d33df58d847c74b27f6c0dae4f1df4bb35510022553901e7d" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "7de9bc76c1a33d44ce44a21b8971e55844149a99111260610aefbd3a54598089" + }, + { + "path": "skills/ln-114-project-docs-creator/SKILL.md", + "sha256": "0b30c63207c1c28d63420562a554d8829757da06f486cda75189695e590ac354" + }, + { + "path": "skills/ln-114-project-docs-creator/diagram.html", + "sha256": "2b51f764ef7bd6abd8227c18c350af24889b7bec0658b750fbc6ede0726c912a" + }, + { + "path": "skills/ln-114-project-docs-creator/references/questions.md", + "sha256": "bae587c23cd1adbb57f4377bc12a9a5d74933a4519b3becc077589927f1276ac" + }, + { + "path": "skills/ln-114-project-docs-creator/references/guides/examples.md", + "sha256": "dcd11c257cc9e73874ba7c644d4010432b0da989e06c4aef0a90d7351767b35f" + }, + { + "path": "skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md", + "sha256": "13679537f1872c52af2434fa5ec7d4c322931c5e92a06778f8f84a2e06fb4c15" + }, + { + "path": "skills/ln-114-project-docs-creator/references/guides/troubleshooting.md", + "sha256": "d6d3eda3eb852c32b54d244b1438b34483d377decb24dd5d44bd31a801aa016d" + }, + { + "path": "skills/ln-114-project-docs-creator/references/guides/critical_questions.md", + "sha256": "0371302d8142a29b3f45dc7a0108875f5a2805bbab8c027e57a4e839a2cf0a45" + }, + { + "path": "skills/ln-114-project-docs-creator/references/guides/template_mappings.md", + "sha256": "b312ec3f4e606953f735b97fc4c74679b53d49b589aa4ff8ac8e69eb22abe0fd" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/database_schema_template.md", + "sha256": "c94b3316391b59b4b62095e922be29576ee82683d39566bf90aaecb08f6f054b" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/design_guidelines_template.md", + "sha256": "63b56b09825e2d02bbcc365be3a9b48837a368a72e7da52baf673adcbd9b1df3" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/architecture_template.md", + "sha256": "5f02bc71ca3c6e41b36ee583eef4123d08a7f049f2a6c8546fe84d04c98468f1" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/requirements_template.md", + "sha256": "ab9f078fc591cfa89b5befb33ad513e4b59c8da1ceeeeb40bc1aa8c6e6cc6b0b" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/runbook_template.md", + "sha256": "0b15019222e2a0bb7b1c40166d1c128d2abeb06c02646fbb2328f90a6e863f02" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/tech_stack_template.md", + "sha256": "473843f05e9306a63760001cb66007bb1eae31de545c956ff943d819668efa58" + }, + { + "path": "skills/ln-114-project-docs-creator/references/templates/api_spec_template.md", + "sha256": "7cbe4d10c3132eb1f508d8c2ab5c77eb0e66821b7a63fae05f1eef82a57ccb32" + }, + { + "path": "skills/ln-341-code-quality-checker/SKILL.md", + "sha256": "a47925903f007caa525dc5b97463c7916c5d6257762dbf42bbf5d89141374a80" + }, + { + "path": "skills/ln-341-code-quality-checker/diagram.html", + "sha256": "c69cdbdf38d8594587ec67d007dbd899adc13c217088f87c231557ec73067762" + }, + { + "path": "skills/ln-341-code-quality-checker/references/kiss_violations.md", + "sha256": "a58e6d02a5de14e3abd137aa9ebd5564833146dfbbad1da51738f75d0bae3c62" + }, + { + "path": "skills/ln-341-code-quality-checker/references/dry_violations.md", + "sha256": "722d1bf3661e361e026bd4ab99d000308246ab9c29870c9a88cd02150f9b3190" + }, + { + "path": "skills/ln-341-code-quality-checker/references/architecture_violations.md", + "sha256": "a66c436dad5221795d7bca4743fe10003da421b8d692da186ab588d0ce78d7a6" + }, + { + "path": "skills/ln-341-code-quality-checker/references/yagni_violations.md", + "sha256": "6087206f7e7237a050dca51a19736a8d98b333e7d0978e7562107a9871e6f961" + }, + { + "path": "skills/ln-342-regression-checker/SKILL.md", + "sha256": "028420522831da6dd6940cce1e919f6b1b2e591cee46ba369e2f09aa3a3e9271" + }, + { + "path": "skills/ln-342-regression-checker/diagram.html", + "sha256": "0098c33e32f91c9981e3347540d48d156839bb15eefaa94c3547c634b98ca074" + }, + { + "path": "skills/ln-342-regression-checker/references/pytest_configuration.md", + "sha256": "c664f9646f5b09abb8d873bff508733317db26c5f174bd1b8b05dbb8657ff849" + }, + { + "path": "skills/ln-210-epic-coordinator/SKILL.md", + "sha256": "545bc3492d638c157b863f6fcecf789b1527f842294dc6cc56b5313e99e312a1" + }, + { + "path": "skills/ln-210-epic-coordinator/diagram.html", + "sha256": "df1dcda2c35ba6804fcdb167733c7c1b22f6e8c8f7c89664a05dd62a2d51cc69" + }, + { + "path": "skills/ln-210-epic-coordinator/references/epic_template_universal.md", + "sha256": "1b7620644f028f1a757b267a9baea9fcfb047a4d22bbeb4bf0c831391a3c964b" + }, + { + "path": "skills/ln-210-epic-coordinator/references/linear_integration.md", + "sha256": "37c69c6d21bc69510bdbce4a4b6dee79220cae8849a73d1a5eded83356a5c917" + }, + { + "path": "skills/ln-220-story-coordinator/SKILL.md", + "sha256": "c828e4d4b456f7ef567efd4b0e7000b57db12292ea685080bc3a496b8de3b56e" + }, + { + "path": "skills/ln-220-story-coordinator/diagram.html", + "sha256": "ac4a4e3216b029c954a698a847e0d605e473c702c537b65bd98b86a74e83be0e" + }, + { + "path": "skills/ln-220-story-coordinator/references/replan_algorithm.md", + "sha256": "9a2ae22ed80a461ad582c331dfe3403c60d5c436200448c17ea7a53142aac99f" + }, + { + "path": "skills/ln-110-documents-pipeline/SKILL.md", + "sha256": "1aac9010ca641d1405cbef8d146779dc4160472d382f23511aad3eb9514cde0d" + }, + { + "path": "skills/ln-110-documents-pipeline/diagram.html", + "sha256": "813b64616c1cbb51dea93fce15548c24428d89365c42eca1999cac972f54a98a" + }, + { + "path": "skills/ln-321-guide-creator/SKILL.md", + "sha256": "e0f3eb792e6a6017ab72fe79a4a4ef764a86338145ec4333686c20f6201ed08a" + }, + { + "path": "skills/ln-321-guide-creator/diagram.html", + "sha256": "e40d6e55464d52443b730d26466543f42c3d69d16a3cdea5275097ce67f0cd41" + }, + { + "path": "skills/ln-321-guide-creator/references/guide_template.md", + "sha256": "dfa71fb2c9ce740353bd092917d7a73e6924aea06f1d2ecdabcf5418a3fd62c7" + }, + { + "path": "skills/ln-113-tasks-docs-creator/SKILL.md", + "sha256": "1da167b0266348b5e19b697c7128970d6b02e3cddabafe12c051de64d4f77d78" + }, + { + "path": "skills/ln-113-tasks-docs-creator/diagram.html", + "sha256": "5ba7e41c7060b2382ae44fa0cb0d8000445ee064557e04493aadd46b7d150971" + }, + { + "path": "skills/ln-113-tasks-docs-creator/references/kanban_board_template.md", + "sha256": "ee0e557838bceef53d2ad7bfc5f447e15c2fa84bee94b524a4c317aef75ed563" + }, + { + "path": "skills/ln-113-tasks-docs-creator/references/questions.md", + "sha256": "9a2ca0ea70596fac07d73d4cfbd6cd67bf2da9800e66d785d58270a84645e43f" + }, + { + "path": "skills/ln-113-tasks-docs-creator/references/tasks_readme_template.md", + "sha256": "49f2d67ce2ffbedc68833f2a0546d256b18db942ff11e94717bff4c4e0abedb0" + }, + { + "path": "skills/ln-200-scope-decomposer/SKILL.md", + "sha256": "37cb04bce317cb5b36b83934b79446e485da62872e1b93611d0035295cf0271c" + }, + { + "path": "skills/ln-200-scope-decomposer/diagram.html", + "sha256": "6631211204d3ecce37776b80ae54ac2550252b7e1a72a53c48add4268837fbb0" + }, + { + "path": "skills/ln-322-adr-creator/SKILL.md", + "sha256": "d8b0d42dd2191cdae3c20c54e1a03a486357ccc80cb20687ba53ed837d5068cc" + }, + { + "path": "skills/ln-322-adr-creator/diagram.html", + "sha256": "b6029c6098986728edab23a48115fe33043a903e69c87b4b05711514d2a9055a" + }, + { + "path": "skills/ln-322-adr-creator/references/adr_template.md", + "sha256": "ba6a7bee77668a00e6df4018dc4be8801aef04ec12551e0557e71edfb44cd48f" + }, + { + "path": "skills/ln-332-task-reviewer/SKILL.md", + "sha256": "bb870abd0852d2284daccf071cf9621329edcef78e75cc6a3bb15b344ce995a4" + }, + { + "path": "skills/ln-332-task-reviewer/diagram.html", + "sha256": "0bd8a2461efa9ce220d320b1e66704f832af91416f568045ab3ce63312531514" + }, + { + "path": "skills/ln-112-reference-docs-creator/SKILL.md", + "sha256": "0cf1a41637d88d98aed7f094fcbce59fe77068a07379a0b0129dc4debe6857a4" + }, + { + "path": "skills/ln-112-reference-docs-creator/diagram.html", + "sha256": "654ceeb4ac9594bc3465098d1a07d09f0c8e90b6978b8197c3321b42e4300819" + }, + { + "path": "skills/ln-112-reference-docs-creator/references/reference_readme_template.md", + "sha256": "dd5c320349bc3dc9916a0da67d525fd225f45f1e7e02d3b7ae663f4f8e57f272" + }, + { + "path": "skills/ln-112-reference-docs-creator/references/questions.md", + "sha256": "34693dc279453ff4b1e9317674df2d00d6fa191a5402936d717ce89d4f4f5850" + }, + { + "path": "skills/ln-343-manual-tester/SKILL.md", + "sha256": "eeb8f431dd48e7e6e77e35a44a463f473ca12f21a0b88dc89094fcc7b0fb138a" + }, + { + "path": "skills/ln-343-manual-tester/diagram.html", + "sha256": "a00cd2e558105b25dc9fc272c04492a6cb841301dbe4cd3d6dc8c647098d1349" + }, + { + "path": "skills/ln-343-manual-tester/references/test_result_format_v1.md", + "sha256": "ba736b4215c492f8ca82aa63bd66fc27d4db9e0b50d5b54bd1a0ff4f596efbca" + }, + { + "path": "skills/ln-343-manual-tester/references/puppeteer_patterns.md", + "sha256": "2d0402214ffe0a4921afa332ef4d9bd839eaaae485b246878d2a6abc86269091" + }, + { + "path": "skills/ln-221-standards-researcher/SKILL.md", + "sha256": "0d43f6f6b114faf1a6069017c3676954211c9ffbec7b094b93ccf44fde649d5e" + }, + { + "path": "skills/ln-221-standards-researcher/diagram.html", + "sha256": "f2827ad4d5ecccbd2980e76ff3e5bf5030a075953019e9f89e8c3c074037f082" + }, + { + "path": "skills/ln-221-standards-researcher/references/research_guidelines.md", + "sha256": "470816054e7c50f29ffb6c72e8f27599a94934c91fab8a490e345e361e30552f" + }, + { + "path": "skills/ln-350-story-test-planner/SKILL.md", + "sha256": "781818c3411bd49d5b8e13ccd097af675e2e8124b4d897a1ebb151b70a611a78" + }, + { + "path": "skills/ln-350-story-test-planner/diagram.html", + "sha256": "6b26faff8e462f02aea217f41c4b7bba246044fa75470d6bbe431a8ca67a66a5" + }, + { + "path": "skills/ln-350-story-test-planner/references/risk_based_testing_examples.md", + "sha256": "c3dbb2d03faa3c60b38e6915d2af2105a52943ceeb3a3301be2b05a218d7cbde" + }, + { + "path": "skills/ln-350-story-test-planner/references/risk_based_testing_guide.md", + "sha256": "b4da291c4383aebd23760df78e43489ba1e39191f7807d736bef91c775b98570" + }, + { + "path": "skills/ln-331-task-executor/SKILL.md", + "sha256": "0cf85d5820a025fbf267f3109694f539b38464b3dc7b36ab52a0d9325537651e" + }, + { + "path": "skills/ln-331-task-executor/diagram.html", + "sha256": "71ec0e399a9ca7fa382b7747e41ff625bbe4e1c5aeefb289bc609526b618c890" + }, + { + "path": "skills/ln-115-presentation-creator/presentation_final.html", + "sha256": "bc920144bbdc6e33a4798697e9820a9e76671703f180b0ae26e308c29993920a" + }, + { + "path": "skills/ln-115-presentation-creator/SKILL.md", + "sha256": "b12a94347da3eeed8ed52705673885536bbbcb9b9988949d62003c7943c3bf8f" + }, + { + "path": "skills/ln-115-presentation-creator/diagram.html", + "sha256": "48ac4849a305a90f3e9edb427d3344e37467a723faa6d43d48440be671807970" + }, + { + "path": "skills/ln-115-presentation-creator/references/styles.css", + "sha256": "671192645a45926e9eb8214c02c2bff5b6fa070aa7c633e163f3d200cec934a0" + }, + { + "path": "skills/ln-115-presentation-creator/references/build-presentation.js", + "sha256": "d0284169114eca4b936b638088ce3a4e391006b21ab10caf50b5d16f2310b7d6" + }, + { + "path": "skills/ln-115-presentation-creator/references/scripts.js", + "sha256": "b19dab280f561f7b14add9300925edaab7141cb6bada4511003e892108f1fc3e" + }, + { + "path": "skills/ln-115-presentation-creator/references/presentation_template.html", + "sha256": "c865ac86aa2d9f0bb81f72a275606472787c06dff182396785f4e3a1f805b3ae" + }, + { + "path": "skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md", + "sha256": "9944d22623ef7dce02e75ecb5478a19fba57dba12ff0f07d4a472f002feff878" + }, + { + "path": "skills/ln-115-presentation-creator/references/mermaid_guidelines.md", + "sha256": "39cfdb30a2f36c3e0cb9e2deed01e469210579b8636056a490995be4e3b500fe" + }, + { + "path": "skills/ln-115-presentation-creator/references/presentation_readme_template.md", + "sha256": "d97890ed3f8fc27e93ea1378e98f8eb1a55c1cac9fe65ad789d87325747d4071" + }, + { + "path": "skills/ln-115-presentation-creator/references/tabs/tab_guides.html", + "sha256": "ec0a02634fff8ff8c0225e7054ba04a83e813fcc5fbed80dcae106088287585f" + }, + { + "path": "skills/ln-115-presentation-creator/references/tabs/tab_overview.html", + "sha256": "434de6ac5f0797cab943c6e1bec11034bedc29489f62c30a3dc16fc0e7f7daea" + }, + { + "path": "skills/ln-115-presentation-creator/references/tabs/tab_architecture.html", + "sha256": "35a3813f64d35375d595e6b9c77f791a674ec8d57f8f4ae492eb86d2cc0d8648" + }, + { + "path": "skills/ln-115-presentation-creator/references/tabs/tab_roadmap.html", + "sha256": "f5c3318fa3d97d2cbe414c1725c1b91a057bda95040d08933b08e05f3289ccd3" + }, + { + "path": "skills/ln-115-presentation-creator/references/tabs/tab_technical_spec.html", + "sha256": "5514065b91a6730bead1ca6125d87652e7f2842f2e26cda228126c7b36fa0d97" + }, + { + "path": "skills/ln-115-presentation-creator/references/tabs/tab_requirements.html", + "sha256": "2e593e35854b1b03d3017700a396ff9a5a12221b2b8635990ff8383df313bf3b" + }, + { + "path": "skills/ln-222-story-creator/SKILL.md", + "sha256": "7d8fbd74218834dc87a683028011c8b0ed54a1b19c8b73f5b6f2d76dcd08e5aa" + }, + { + "path": "skills/ln-222-story-creator/diagram.html", + "sha256": "bbe10c20c618cd3871924379b5246bf8f4e9f4e487b80682f0a5bbe275d7d835" + }, + { + "path": "skills/ln-222-story-creator/references/story_template_universal.md", + "sha256": "d3d978609d67332eb3eb6e7b5d386d22f47fb6b21228120cbb4bf4da22d011d2" + }, + { + "path": "skills/ln-330-story-executor/SKILL.md", + "sha256": "1bfa718d5473905f83c1899cbd9b0d0e312fb224e7c2c98d07fa62f61e73b174" + }, + { + "path": "skills/ln-330-story-executor/diagram.html", + "sha256": "653e39266b105788ca30ace72e9bd47812ae5c847809f9d2cb89891a646e7183" + }, + { + "path": "skills/ln-320-story-validator/SKILL.md", + "sha256": "39895a71a5cf8d8089052b6b5c1e700b63952250b9369fc6b8abdf963a08f5fb" + }, + { + "path": "skills/ln-320-story-validator/diagram.html", + "sha256": "50d6f3f3a14f870dfc147815fac280fa2ae211e22238a0886366cf48a3be1b1c" + }, + { + "path": "skills/ln-320-story-validator/references/verification_checklist.md", + "sha256": "c0ac00391e31e6da140dfc2c04e5959923006bc5e481d0905a1e08faf1f691a6" + }, + { + "path": "skills/ln-223-story-replanner/SKILL.md", + "sha256": "628bef407abdd64bbd96d180e28e1a0272b32c3364d5fd9dac5a0fbdfd2d78e3" + }, + { + "path": "skills/ln-223-story-replanner/diagram.html", + "sha256": "6d4638e3abd99610c913c7fc7d585b87846ea09082303c0e7cba3e02ea590fa0" + }, + { + "path": "skills/ln-223-story-replanner/references/replan_algorithm_stories.md", + "sha256": "2fae471feb65a18fa1a8e2b1bf13cd2b4cfb4917139fe7ebc276431a29c96156" + }, + { + "path": "skills/ln-116-test-docs-creator/SKILL.md", + "sha256": "dba549fd399b90357b76787ac3192d65f9e101c851e398b981693ee7117bd96f" + }, + { + "path": "skills/ln-116-test-docs-creator/diagram.html", + "sha256": "5b384b40245fc3aef506d3de9904238997750dcc5a2ab1989c8f120448fcd2ed" + }, + { + "path": "skills/ln-116-test-docs-creator/references/testing_strategy_template.md", + "sha256": "c62dde97ec2f5139206d93338f24a5c890f02fa5cb2fe61832c011f43c2885c2" + }, + { + "path": "skills/ln-116-test-docs-creator/references/questions.md", + "sha256": "838d32b7d478e1dfe049528150bfd14ec320be70f416a41119116698227f61a5" + }, + { + "path": "skills/ln-116-test-docs-creator/references/tests_readme_template.md", + "sha256": "7d50c7bcaf281ee9cf8c40484e676e50212665e0ff7d654e817103e0d7d73cea" + }, + { + "path": "skills/ln-310-story-decomposer/SKILL.md", + "sha256": "36c3761ff9a62c19ec92419ca6781772353ac6a92dc7c68d89cdb4eace933a85" + }, + { + "path": "skills/ln-310-story-decomposer/diagram.html", + "sha256": "c0b396981effa5c3775704bd9f5a68d0836b0d271e1f8597f377a6bf20cdc59c" + }, + { + "path": "skills/ln-334-test-executor/SKILL.md", + "sha256": "1272bcad54e0104a04804946633484c67759eea76b8e6c30bcc1c2ffa610c412" + }, + { + "path": "skills/ln-334-test-executor/diagram.html", + "sha256": "761c7b815386e9e553f2d418c252d6068baeec32bb3d732e92dd5227877a8703" + }, + { + "path": "skills/ln-323-manual-creator/SKILL.md", + "sha256": "9fc791e5e352aafd5bed2a794fef0a62c884bc90a025eb92e89aaeef04e88f4d" + }, + { + "path": "skills/ln-323-manual-creator/diagram.html", + "sha256": "55f9e437b92fe00ef7923aa70ba2d019f0deb4cb721a37ee2dcea02eb7cfb815" + }, + { + "path": "skills/ln-323-manual-creator/references/manual_template.md", + "sha256": "1e780b6981d7868e26c3a02dd2ee3f032d5f2f5eb3098ff35dafacd73f60e060" + }, + { + "path": "skills/ln-300-story-pipeline/SKILL.md", + "sha256": "e9c7b2523e03f3d40f9774dc96575c246198f6feee0e88b38f63b178e730b261" + }, + { + "path": "skills/ln-300-story-pipeline/diagram.html", + "sha256": "315ce3b292d8d15a4949e6b88135cac7bdc4b88a8d62528b64edb63e5862ff20" + }, + { + "path": "skills/ln-300-story-pipeline/references/checkpoint_format.md", + "sha256": "881cecc62cd6c22b39c9b727d9c2a1e79e5855483fa51e14f051a582970b8aaf" + }, + { + "path": "skills/ln-111-root-docs-creator/SKILL.md", + "sha256": "b88f295c42b5d8f7366e279275473f426728d9834412f9c428aad88b67b10b65" + }, + { + "path": "skills/ln-111-root-docs-creator/diagram.html", + "sha256": "a2893f2c653c3e6e3307a7ac47342e0401f38bd7e7484ca7b2b8ff16a17d69aa" + }, + { + "path": "skills/ln-111-root-docs-creator/references/docs_root_readme_template.md", + "sha256": "c07239d0453bb8c1e6695cf5606bfea2c73a8a00195dfb53d528651207c57ef6" + }, + { + "path": "skills/ln-111-root-docs-creator/references/documentation_standards_template.md", + "sha256": "c457db538a81c139a17e897cd6982bc0a5b8bf3901da8d57b1f16dfdb1ea6f40" + }, + { + "path": "skills/ln-111-root-docs-creator/references/principles_template.md", + "sha256": "5e5cffab666aa7908f4449db2082c078c659d8c8b53d585d413baba39d2ef927" + }, + { + "path": "skills/ln-111-root-docs-creator/references/questions.md", + "sha256": "640a5dfea58db0acaf960061f9c2adafd3e7e2d2ce40edd269d68b06b2f2b995" + }, + { + "path": "skills/ln-111-root-docs-creator/references/claude_md_template.md", + "sha256": "d581676a3150fb28a92912ad98e9d827a1034f9e627975712f6b89aea1dffb0a" + }, + { + "path": "skills/ln-311-task-creator/SKILL.md", + "sha256": "bae23faa5f9aefd66418ecebc0f4a6d1a954444fd8ef9d6d37273bcfba116e2d" + }, + { + "path": "skills/ln-311-task-creator/diagram.html", + "sha256": "009e8aeafa634be9b5984cfb3573a7d235f73cf3ec1612cf1d7a844ac7a99c90" + }, + { + "path": "skills/ln-311-task-creator/references/test_task_template.md", + "sha256": "bd772851cfbbe08fba9f1dd85b78a74fd6ecc3fa121bd74bc1165481f95b7381" + }, + { + "path": "skills/ln-311-task-creator/references/refactoring_task_template.md", + "sha256": "4cb8f4157e1596a5a88ab067fbdad41439dad0464f28e1b4bfa83d961181836f" + }, + { + "path": "skills/ln-311-task-creator/references/task_template_implementation.md", + "sha256": "aff4307891e136cd6637951c3a72929418e2a7c7756de479c75e1e10fb1cd7eb" + }, + { + "path": "skills/ln-312-task-replanner/SKILL.md", + "sha256": "3622c4a450abefbfb7eefc71ba1288dc53c6f60bc03dad451f7029d909ca59ad" + }, + { + "path": "skills/ln-312-task-replanner/diagram.html", + "sha256": "4b51619396e792fe6acb18e01e5ddab3bd91b880daad756d9865064b9b2f21c6" + }, + { + "path": "skills/ln-312-task-replanner/references/replan_algorithm.md", + "sha256": "f6ce2387b31a1bb75fd63ebc178d5c7d9e5459fc07ae7172c0e43507bb2ab90e" + }, + { + "path": "skills/ln-340-story-quality-gate/SKILL.md", + "sha256": "3f0521c0c017254f5da9354c7b07dc01701280eb84b3d51886d79965cee5bc47" + }, + { + "path": "skills/ln-340-story-quality-gate/diagram.html", + "sha256": "e1b9357f07e7f70387773b6465389cecf8286f619898deda67d0d16901ea2b90" + }, + { + "path": "skills/ln-340-story-quality-gate/references/story_review_checklist.md", + "sha256": "5a41138ae3406ab23efad9489ace92c182fe0d4b5fde8b08512f9708bda69c6f" + }, + { + "path": "skills/ln-340-story-quality-gate/references/manual_testing_comment_template.md", + "sha256": "32e18cb4b38607171b897df7812b6072d03b06b4002d671e85f425b1311fc3ae" + }, + { + "path": "skills/ln-333-task-rework/SKILL.md", + "sha256": "405332255efe3ffccd01f39e453f97769578c8c5965c164193f3e203559e22b5" + }, + { + "path": "skills/ln-333-task-rework/diagram.html", + "sha256": "34ab97591b76e9b646a09799358c7bb2604aeefa239e41373d49b4508424dea5" + } + ], + "dirSha256": "96357b5b5b4867fce6ddd1bc70c98c1662669458a19febd933e137c547778782" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/ln-110-documents-pipeline/SKILL.md b/skills/ln-110-documents-pipeline/SKILL.md new file mode 100644 index 0000000..3629adc --- /dev/null +++ b/skills/ln-110-documents-pipeline/SKILL.md @@ -0,0 +1,475 @@ +--- +name: ln-110-documents-pipeline +description: Orchestrates complete doc system via 6 workers (ln-111→ln-116). Each worker self-validates. Phase 4: global cleanup. Idempotent. +--- + +# Documentation Pipeline (Orchestrator) + +This skill orchestrates the creation of a complete documentation system by invoking 6 specialized documentation workers in sequence. Each worker handles one domain (root/reference/tasks/project/presentation/test) and validates its own output, eliminating Worker→Worker coupling. + +## When to Use This Skill + +This skill should be used when: +- Start a new IT project and need complete documentation system at once +- Use automated workflow instead of manually invoking 6 workers +- Create entire documentation structure (CLAUDE.md → docs/ → presentation/) in one go +- Prefer orchestrated CREATE path over manual skill chaining +- Need automatic global cleanup (deduplication, orphaned files, consolidation) + +**Alternative**: If you prefer granular control, invoke workers manually: +1. [ln-111-root-docs-creator](../ln-111-root-docs-creator/SKILL.md) - CLAUDE.md + docs/README.md + documentation_standards.md + principles.md +2. [ln-112-reference-docs-creator](../ln-112-reference-docs-creator/SKILL.md) - reference/ structure +3. [ln-113-tasks-docs-creator](../ln-113-tasks-docs-creator/SKILL.md) - tasks/README.md + kanban +4. [ln-114-project-docs-creator](../ln-114-project-docs-creator/SKILL.md) - project docs +5. [ln-115-presentation-creator](../ln-115-presentation-creator/SKILL.md) - HTML presentation +6. [ln-116-test-docs-creator](../ln-116-test-docs-creator/SKILL.md) - tests/README.md (optional) + +**Note**: Each worker now validates its own output in Phase 2/3. Orchestrator handles global operations only. + +## How It Works + +The skill follows a 5-phase orchestration workflow: User confirmation → Invoke 6 workers sequentially → Global cleanup → Summary. Phase 3 (validation) is intentionally skipped - each worker validates its own output. + +### Phase 1: User Confirmation + +**Objective**: Check existing files, explain workflow, and get user approval. + +**Process**: + +1. **Pre-flight Check** (scan existing documentation): + - Use Glob tool to check all potential files: + - **Root docs** (4 files): `CLAUDE.md`, `docs/README.md`, `docs/documentation_standards.md`, `docs/principles.md` + - **Reference structure** (4 items): `docs/reference/README.md`, `docs/reference/adrs/`, `docs/reference/guides/`, `docs/reference/manuals/` + - **Tasks docs** (2 files): `docs/tasks/README.md`, `docs/tasks/kanban_board.md` + - **Project docs** (up to 7 files): `docs/project/requirements.md`, `architecture.md`, `tech_stack.md`, `api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md` + - **Presentation** (3 items): `docs/presentation/README.md`, `presentation_final.html`, `assets/` directory + - **Test docs** (2 files): `docs/reference/guides/testing-strategy.md`, `tests/README.md` + - Count existing vs missing files + - Show user summary: + ``` + 📊 Documentation Status: + ✓ Found: X existing files + ✗ Missing: Y files + + ⚠️ Pipeline will create ONLY missing files. + ✅ Existing files will be preserved (no overwrites). + ``` + +2. Show user what will be created: + - Root documentation (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md via ln-111-root-docs-creator) + - Reference structure (docs/reference/ via ln-112-reference-docs-creator) + - Task management docs (docs/tasks/ via ln-113-tasks-docs-creator) + - Project documentation (docs/project/ via ln-114-project-docs-creator) + - HTML presentation (docs/presentation/ via ln-115-presentation-creator) + - Test documentation (tests/ via ln-116-test-docs-creator - optional) + - Estimated time: 15-20 minutes with interactive dialog + +3. Ask: "Proceed with creating missing files? (yes/no)" + +4. Ask: "Include test documentation (tests/README.md)? (yes/no)" + +**Output**: File scan summary + user approval + test docs preference + +--- + +### Phase 2: Invoke Workers Sequentially + +**Objective**: Create complete documentation system by invoking 6 workers in order. + +**Process** (AUTOMATIC invocations with Skill tool): + +**2.1 Create Root Documentation**: +- **Invocation**: `Skill(skill: "ln-111-root-docs-creator")` → AUTOMATIC +- **Output**: `CLAUDE.md` + `docs/README.md` (root hub with general standards) + `docs/documentation_standards.md` (60 universal requirements) + `docs/principles.md` (11 development principles) +- **Validation**: ln-111 validates output in Phase 2/3 (SCOPE tags, Maintenance sections) +- **Verify**: All four files exist before continuing + +**2.2 Create Reference Structure**: +- **Invocation**: `Skill(skill: "ln-112-reference-docs-creator")` → AUTOMATIC +- **Output**: `docs/reference/README.md` + `adrs/`, `guides/`, `manuals/` directories + ADR template +- **Validation**: ln-112 validates output in Phase 2/3 +- **Verify**: Reference hub exists before continuing + +**2.3 Create Task Management Docs**: +- **Invocation**: `Skill(skill: "ln-113-tasks-docs-creator")` → AUTOMATIC +- **Output**: `docs/tasks/README.md` + optionally `kanban_board.md` (if user provides Linear config) +- **Validation**: ln-113 validates output in Phase 2/3 +- **Verify**: Tasks README exists before continuing + +**2.4 Create Project Documentation**: +- **Invocation**: `Skill(skill: "ln-114-project-docs-creator")` → AUTOMATIC (requires user interaction for 23 technical questions) +- **Output**: `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional: `api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md` (3-7 documents based on project type) +- **Validation**: ln-114 validates output in Phase 2/3 +- **Verify**: All required project docs exist before continuing + +**2.5 Create HTML Presentation**: +- **Invocation**: `Skill(skill: "ln-115-presentation-creator")` → AUTOMATIC +- **Output**: `docs/presentation/README.md` + `presentation_final.html` + `assets/` +- **Validation**: ln-115 validates output in Phase 2/3 +- **Verify**: Presentation files exist before continuing + +**2.6 Create Test Documentation (Optional)**: +- **Condition**: If user approved test docs in Phase 1 +- **Invocation**: `Skill(skill: "ln-116-test-docs-creator")` → AUTOMATIC +- **Output**: `tests/README.md` (test documentation with Story-Level Test Task Pattern) +- **Validation**: ln-116 validates output in Phase 2/3 +- **Skip**: If "no" → can run ln-116-test-docs-creator later manually + +**Output**: Complete documentation system with all 6 workers completed and validated + +--- + +### Phase 4: Global Cleanup and Consolidation + +**Objective**: Remove duplicates, orphaned files, consolidate knowledge across ALL documentation. + +**Trigger**: Only after ALL workers complete Phase 2/3 validation. + +**Process**: + +**4.1 Scan for duplicate content** + +1. **Read all .md files in docs/** + - Use Glob tool: `pattern: "docs/**/*.md"` + - Store list of all documentation files + +2. **Identify duplicate sections:** + - For each file: + - Read file content + - Extract section headers (##, ###) + - Extract section content (text between headers) + - Compare sections across files: + - If 2+ sections have: + - Same heading (case-insensitive) + - >80% content similarity (simple word overlap check) + - Mark as duplicate + +3. **Determine canonical version:** + - Rules for canonical location: + - "Development Principles" → principles.md (always canonical) + - "Testing Strategy" → testing-strategy.md (always canonical) + - "Linear Configuration" → tasks/kanban_board.md (always canonical) + - For other duplicates: Keep in FIRST file encountered (alphabetical order) + +4. **Remove duplicates:** + - For each duplicate section: + - Use Edit tool to delete from non-canonical files + - Use Edit tool to add link to canonical location: + ```markdown + See [Development Principles](../principles.md#development-principles) for details. + ``` + - Track count of removed duplicates + +5. **Log results:** + - "✓ Removed {count} duplicate sections" + - List: "{section_name} removed from {file} (canonical: {canonical_file})" + +**4.2 Scan for orphaned files** + +1. **List all .md files in docs/** + - Use Glob tool: `pattern: "docs/**/*.md"` + +2. **Check against expected structure:** + - Expected files (created by workers): + - docs/CLAUDE.md + - docs/README.md + - docs/documentation_standards.md + - docs/principles.md + - docs/project/requirements.md + - docs/project/architecture.md + - docs/project/tech_stack.md + - docs/project/api_spec.md (conditional) + - docs/project/database_schema.md (conditional) + - docs/project/design_guidelines.md (conditional) + - docs/project/runbook.md (conditional) + - docs/reference/README.md + - docs/reference/adrs/*.md (user-created) + - docs/reference/guides/*.md (user-created) + - docs/reference/manuals/*.md (user-created) + - docs/tasks/README.md + - docs/tasks/kanban_board.md + - docs/testing-strategy.md + - tests/README.md + - Any file NOT in this list = orphaned + +3. **Move orphaned files to archive:** + - Create `.archive/YYYY-MM-DD/` directory (current date) + - For each orphaned file: + - Use Bash tool: `mv {file_path} .archive/YYYY-MM-DD/` + - Log: "Archived {file_name} (not in expected structure)" + - Track count + +4. **Log results:** + - "✓ Archived {count} orphaned files to .archive/{date}/" + - List archived files + +**4.3 Consolidate knowledge** + +1. **Identify scattered information:** + - Known patterns: + - Linear config scattered: kanban_board.md + tasks/README.md + - Development principles scattered: principles.md + architecture.md + CLAUDE.md + - Testing info scattered: testing-strategy.md + tests/README.md + architecture.md + +2. **For each scattered concept:** + - Determine Single Source of Truth (SSoT): + - Linear config → kanban_board.md + - Development principles → principles.md + - Testing strategy → testing-strategy.md + +3. **Update non-SSoT files:** + - Use Edit tool to replace duplicate content with link: + ```markdown + See [Linear Configuration](../tasks/kanban_board.md#linear-configuration) for team ID and settings. + ``` + - Track consolidation count + +4. **Log results:** + - "✓ Consolidated {count} scattered concepts" + - List: "{concept} consolidated to {SSoT_file}" + +**4.4 Cross-link validation** + +1. **Scan all .md files for internal links:** + - For each file: + - Read content + - Extract all markdown links: `[text](path)` + - Filter internal links (relative paths, not http://) + +2. **Verify link targets exist:** + - For each link: + - Resolve relative path + - Check if target file exists (Glob tool) + - If missing: Mark as broken + +3. **Fix broken links:** + - For each broken link: + - If target was archived: Update link to archive path + - If target never existed: Remove link (convert to plain text) + - Track fix count + +4. **Add missing critical links:** + - **CLAUDE.md → docs/README.md:** + - Read CLAUDE.md + - Check for link to docs/README.md + - If missing: Add in "Documentation Hub" section + - **docs/README.md → section READMEs:** + - Check for links to project/, reference/, tasks/, tests/ READMEs + - If missing: Add + - Track added links count + +5. **Log results:** + - "✓ Fixed {count} broken links" + - "✓ Added {count} missing critical links" + - List changes + +**4.5 Final report** + +``` +✅ Global Cleanup Complete: + +Structure: +- Removed {N} duplicate sections (canonical: principles.md) +- Archived {N} orphaned files to .archive/YYYY-MM-DD/ + - list of archived files +- Consolidated {N} scattered concepts + +Links: +- Fixed {N} broken links +- Added {N} missing critical links: + - list of added links +``` + +**Output**: All documentation cleaned up, duplicates removed, orphaned files archived, knowledge consolidated, cross-links validated + +--- + +### Phase 5: Summary and Next Steps + +**Objective**: Provide complete overview of created system. + +**Process**: +1. List all created files with sizes: + - `CLAUDE.md` (project entry point) + - `docs/README.md` (root documentation hub) + - `docs/documentation_standards.md` (60 universal requirements) + - `docs/principles.md` (11 development principles) + - `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional documents (3-7 total) + - `docs/reference/README.md` (reference hub with empty adrs/, guides/, manuals/ directories) + - `docs/tasks/README.md` + optionally `kanban_board.md` + - `docs/presentation/README.md` + `presentation_final.html` + - `tests/README.md` (if created) + +2. Show documentation system features: + - ✅ SCOPE tags (document boundaries defined) + - ✅ Maintenance sections (update triggers + verification) + - ✅ README hub (central navigation) + - ✅ DAG structure (Directed Acyclic Graph navigation) + - ✅ Living documentation ready + - ✅ Deduplicated content (canonical sources only) + - ✅ Validated cross-links (no broken links) + +3. Recommend next steps: + - "Review generated documentation (CLAUDE.md → docs/)" + - "Open docs/presentation/presentation_final.html in browser" + - "Run ln-210-epic-coordinator to decompose scope into Epics" + - "Share documentation with technical stakeholders" + +**Output**: Summary message with file list and recommendations + +--- + +## Complete Output Structure + +``` +project_root/ +├── CLAUDE.md # ← Project entry point (link to docs/) +├── docs/ +│ ├── README.md # ← Root documentation hub (general standards) +│ ├── documentation_standards.md # ← 60 universal requirements (Claude Code + industry standards) +│ ├── principles.md # ← 11 development principles (Standards First, YAGNI, KISS, DRY, etc.) +│ ├── project/ +│ │ ├── requirements.md # ← Functional Requirements (NO NFR per project policy) +│ │ ├── architecture.md # ← arc42-based architecture with C4 Model +│ │ ├── tech_stack.md # ← Technology versions, Docker config +│ │ ├── api_spec.md # ← API endpoints (conditional) +│ │ ├── database_schema.md # ← Database schema (conditional) +│ │ ├── design_guidelines.md # ← UI/UX system (conditional) +│ │ └── runbook.md # ← Operations guide (conditional) +│ ├── reference/ +│ │ ├── README.md # ← Reference documentation hub (registries) +│ │ ├── adrs/ # ← Empty, ready for ADRs +│ │ ├── guides/ # ← Empty, ready for guides +│ │ └── manuals/ # ← Empty, ready for manuals +│ ├── tasks/ +│ │ ├── README.md # ← Task management system rules +│ │ └── kanban_board.md # ← Linear integration (optional) +│ └── presentation/ +│ ├── README.md # ← Navigation hub for presentation +│ ├── presentation_final.html # ← Final standalone HTML (~130-180 KB) +│ └── assets/ # ← Modular HTML structure +└── tests/ + └── README.md # ← Test documentation (optional) +``` + +--- + +## Integration with Project Workflow + +**Recommended workflow for new projects:** + +1. **ln-110-documents-pipeline** (this skill) - Create complete documentation system +2. **ln-210-epic-coordinator** - Decompose scope into Epics (Linear Projects) +3. **ln-220-story-coordinator** - Create User Stories for each Epic (automatic decomposition + replan) +4. **ln-310-story-decomposer** - Break down Stories into implementation tasks (automatic decomposition + replan) +5. **ln-320-story-validator** - Verify Stories before development +6. **ln-330-story-executor** - Orchestrate Story implementation +7. **ln-340-story-quality-gate** - Review completed Stories + +--- + +## Advantages of Orchestrator Approach + +**Benefits:** +- ✅ Single command creates complete system +- ✅ No need to remember skill sequence +- ✅ Automated skill chaining +- ✅ Consistent output every time +- ✅ Time-saving (one invocation vs 2-3 manual invocations) +- ✅ **Idempotent**: Safe to run multiple times - preserves existing files, creates only missing ones +- ✅ **Pre-flight check**: Shows file scan summary before execution +- ✅ **Global cleanup**: Automatic deduplication, orphaned files archival, knowledge consolidation +- ✅ **Validated cross-links**: No broken links in documentation + +**Trade-offs:** +- ⚠️ Less granular control (can't skip ln-111-docs-creator phases) +- ⚠️ Longer execution time (15-20 minutes) +- ⚠️ Global cleanup runs even if only one file was created + +**When to use manual approach instead:** +- Need only HTML rebuild → use [ln-115-presentation-creator](../ln-115-presentation-creator/SKILL.md) +- Need one specific ADR → use [ln-322-adr-creator](../ln-322-adr-creator/SKILL.md) + +--- + +## Error Handling + +If any invoked skill fails: +1. Notify user which skill failed +2. Show error message from failed skill +3. Recommend manual invocation for debugging +4. List already completed steps (partial progress) + +--- + +## Technical Implementation Notes + +**Skill Invocation:** +- Uses **Skill tool** with command parameter +- Waits for each skill to complete before proceeding +- Verifies output files exist before moving to next phase + +**File Verification:** +- Uses **Glob** tool to check docs/project/ structure +- Lists file sizes for user confirmation +- Warns if expected files missing + +**Global Cleanup:** +- Uses **Glob** tool to find all .md files +- Uses **Read** tool to analyze content +- Uses **Edit** tool to remove duplicates and add links +- Uses **Bash** tool to archive orphaned files + +**Standards Compliance:** +- All output follows same standards as underlying skills +- ISO/IEC/IEEE 29148:2018 (Requirements) +- ISO/IEC/IEEE 42010:2022 (Architecture) +- arc42 + C4 Model + Michael Nygard's ADR Format + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +**✅ User Confirmation (Phase 1):** +- [ ] Workflow explained to user (6 workers: ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116) +- [ ] User approved: "Proceed with complete documentation system creation? (yes/no)" +- [ ] Test docs preference captured: "Include test documentation? (yes/no)" + +**✅ Workers Invoked Sequentially (Phase 2):** +- [ ] ln-111-root-docs-creator invoked → Output verified: `CLAUDE.md` + `docs/README.md` + `docs/documentation_standards.md` + `docs/principles.md` +- [ ] ln-112-reference-docs-creator invoked → Output verified: `docs/reference/README.md` + directories (adrs/, guides/, manuals/) +- [ ] ln-113-tasks-docs-creator invoked → Output verified: `docs/tasks/README.md` + optionally `kanban_board.md` +- [ ] ln-114-project-docs-creator invoked → Output verified: `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional documents (3-7 files) +- [ ] ln-115-presentation-creator invoked → Output verified: `docs/presentation/README.md` + `presentation_final.html` + `assets/` +- [ ] ln-116-test-docs-creator invoked (if enabled) → Output verified: `tests/README.md` +- [ ] Each worker validated its own output (SCOPE tags, Maintenance sections, POSIX compliance) + +**✅ File Verification Complete:** +- [ ] All expected files exist (Glob tool used to verify structure) +- [ ] File sizes listed for user confirmation +- [ ] Warning displayed if expected files missing + +**✅ Global Cleanup Complete (Phase 4):** +- [ ] 4.1: Duplicate sections identified and removed (>80% similarity) +- [ ] 4.1: Links added to canonical locations (principles.md, testing-strategy.md, kanban_board.md) +- [ ] 4.2: Orphaned files archived to `.archive/YYYY-MM-DD/` +- [ ] 4.3: Scattered concepts consolidated to Single Source of Truth (SSoT) +- [ ] 4.4: Internal links validated (broken links fixed, critical links added) +- [ ] 4.5: Final report generated (counts, lists, actions) + +**✅ Summary Displayed (Phase 5):** +- [ ] All created files listed with sizes +- [ ] Documentation system features highlighted (SCOPE tags, Maintenance sections, README hubs, DAG structure, deduplicated content, validated links) +- [ ] Next steps recommended (ln-210-epic-coordinator) + +**✅ Error Handling (if applicable):** +- [ ] If any worker failed: User notified which worker failed, error message shown, manual invocation recommended, partial progress listed + +**Output:** Complete documentation system (CLAUDE.md + docs/ with README.md, documentation_standards.md, principles.md + presentation/ + optionally tests/) with global cleanup (no duplicates, no orphaned files, consolidated knowledge, validated cross-links) + +--- + +**Version:** 6.0.0 (MAJOR: Removed Phase 3 validation - delegated to workers Phase 2/3. Added Phase 4 Global Cleanup: deduplication, orphaned files, consolidation, cross-link validation. Orchestrator now coordinates workers (Phase 2) + global operations (Phase 4). All workers are idempotent.) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-110-documents-pipeline/diagram.html b/skills/ln-110-documents-pipeline/diagram.html new file mode 100644 index 0000000..465ae11 --- /dev/null +++ b/skills/ln-110-documents-pipeline/diagram.html @@ -0,0 +1,123 @@ + + + + + + ln-110-documents-pipeline - State Diagram + + + + +
+
+

🎯 ln-110-documents-pipeline

+

Documentation Pipeline Orchestrator - State Diagram

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Create complete documentation system (CLAUDE.md + docs/ + presentation/) in one command
    • +
  • Orchestrates: 6 workers (ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116)
    • +
  • Phases: 5 phases (Phase 1 User Confirmation → Phase 2 Worker Invocation → Phase 4 Global Cleanup → Phase 5 Summary)
    • +
  • Error handling: Stops if any invoked worker fails
    • +
+
+ +
+
+
+ Orchestration Action +
+
+
+ Completion Check +
+
+
+ Error State +
+
+ +
+
+graph TD + Start([Start: ln-110-documents-pipeline]) --> Phase1[Phase 1: User Confirmation
Explain workflow + get approval] + + Phase1 --> Approved{User
approved?} + Approved -->|No| Cancelled([Cancelled by user]) + Approved -->|Yes| W1[Phase 2.1: Invoke ln-111-root-docs-creator
CLAUDE.md + docs/README.md] + + W1 --> W1Check{ln-111
completed?} + W1Check -->|No| Error[Error: Worker failed] + W1Check -->|Yes| W2[Phase 2.2: Invoke ln-112-reference-docs-creator
docs/reference/ structure] + + W2 --> W2Check{ln-112
completed?} + W2Check -->|No| Error + W2Check -->|Yes| W3[Phase 2.3: Invoke ln-113-tasks-docs-creator
docs/tasks/ + kanban_board.md] + + W3 --> W3Check{ln-113
completed?} + W3Check -->|No| Error + W3Check -->|Yes| W4[Phase 2.4: Invoke ln-114-project-docs-creator
docs/project/ documentation] + + W4 --> W4Check{ln-114
completed?} + W4Check -->|No| Error + W4Check -->|Yes| W5[Phase 2.5: Invoke ln-115-presentation-creator
docs/presentation/ HTML] + + W5 --> W5Check{ln-115
completed?} + W5Check -->|No| Error + W5Check -->|Yes| W6[Phase 2.6: Invoke ln-116-test-docs-creator
tests/README.md optional] + + W6 --> W6Check{ln-116
completed?} + W6Check -->|No| Error + W6Check -->|Yes| Phase4[Phase 4: Global Cleanup
Deduplication + Orphan removal
Consolidation + Cross-link validation] + + Phase4 --> Phase4Check{Phase 4
completed?} + Phase4Check -->|No| Error + Phase4Check -->|Yes| Summary[Phase 5: Summary
Display completion report] + + Summary --> End([End: Documentation created]) + Error --> End + Cancelled --> End + + %% Styling + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px + classDef error fill:#FFCDD2,stroke:#C62828,stroke-width:2px + + class Phase1,W1,W2,W3,W4,W5,W6,Phase4,Summary action + class Approved,W1Check,W2Check,W3Check,W4Check,W5Check,W6Check,Phase4Check decision + class Error error +
+
+ +
+

🔑 Key Features

+
    +
  • One Command: Creates entire documentation system in single invocation
    • +
  • Sequential Execution: 6 workers invoked in order (15-20 minutes total)
    • +
  • Global Cleanup: Phase 4 removes duplicates, orphaned files, consolidates knowledge, validates cross-links
    • +
  • Domain Separation: Each worker creates specific documentation area
    • +
  • Error Handling: Stops execution if any worker fails, shows partial progress
    • +
+
+ +
+

Generated for ln-110-documents-pipeline skill | Version 6.0.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-18

+
+
+ + + + diff --git a/skills/ln-111-root-docs-creator/SKILL.md b/skills/ln-111-root-docs-creator/SKILL.md new file mode 100644 index 0000000..3048902 --- /dev/null +++ b/skills/ln-111-root-docs-creator/SKILL.md @@ -0,0 +1,444 @@ +--- +name: ln-111-root-docs-creator +description: Creates root documentation (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md). First worker in ln-110-documents-pipeline. Establishes documentation structure and standards. +--- + +# Root Documentation Creator + +This skill creates the root documentation entry points for a project: CLAUDE.md (project root), docs/README.md (documentation hub with general standards), docs/documentation_standards.md (60 universal documentation requirements), and docs/principles.md (11 development principles). + +## When to Use This Skill + +**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator. + +This skill should be used directly when: +- Creating only root documentation files (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md) +- Setting up documentation structure for existing project +- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup) + +## How It Works + +The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation. + +--- + +### Phase 1: Create Structure + +**Objective**: Create all 4 root documentation files. + +**Process**: + +**1.1 Create CLAUDE.md**: +- Check if CLAUDE.md exists in project root +- If exists: + - Read first 50 lines + - Check for link to `docs/README.md` + - If missing: + - Use Edit tool to add Documentation section: + ```markdown + ## Documentation + + Project documentation: [docs/README.md](docs/README.md) + ``` + - Log: "✓ Added docs link to existing CLAUDE.md" + - If present: + - Log: "✓ CLAUDE.md already has docs link" +- If NOT exists: + - Ask user: "Project name?" + - Ask user: "Brief project description (1-2 sentences)?" + - Copy template: `references/claude_md_template.md` → `CLAUDE.md` + - Replace placeholders: + - `{{PROJECT_NAME}}` — user input + - `{{PROJECT_DESCRIPTION}}` — user input + - `{{DATE}}` — current date (YYYY-MM-DD) + - Log: "✓ Created CLAUDE.md" + +**1.2 Create docs/README.md**: +- Check if docs/README.md exists +- If exists: + - Skip creation + - Log: "✓ docs/README.md already exists" +- If NOT exists: + - Create docs/ directory if missing + - Copy template: `references/docs_root_readme_template.md` → `docs/README.md` + - Ask user: "Documentation status? (Draft/Active)" + - Replace placeholders: + - `{{VERSION}}` — "1.0.0" + - `{{DATE}}` — current date (YYYY-MM-DD) + - `{{STATUS}}` — user input + - Log: "✓ Created docs/README.md" + +**1.3 Create docs/documentation_standards.md**: +- Check if docs/documentation_standards.md exists +- If exists: + - Skip creation + - Log: "✓ docs/documentation_standards.md already exists" +- If NOT exists: + - Copy template: `references/documentation_standards_template.md` → `docs/documentation_standards.md` + - Replace placeholders: + - `{{DATE}}` — current date (YYYY-MM-DD) + - `{{PROJECT_NAME}}` — from 1.1 (if collected) + - Log: "✓ Created docs/documentation_standards.md" + +**1.4 Create docs/principles.md**: +- Check if docs/principles.md exists +- If exists: + - Skip creation + - Log: "✓ docs/principles.md already exists" +- If NOT exists: + - Copy template: `references/principles_template.md` → `docs/principles.md` + - Replace placeholders: + - `{{DATE}}` — current date (YYYY-MM-DD) + - Log: "✓ Created docs/principles.md" + +**1.5 Output**: +``` +CLAUDE.md # Created or updated with docs link +docs/ +├── README.md # Created or existing +├── documentation_standards.md # Created or existing +└── principles.md # Created or existing +``` + +--- + +### Phase 2: Validate Structure + +**Objective**: Ensure all 4 files comply with structural requirements and auto-fix violations. + +**Process**: + +**2.1 Check SCOPE tags**: +- Read first 10 lines of CLAUDE.md +- Check for `> **SCOPE:**` or `` tag +- If missing: + - Use Edit tool to add SCOPE tag after first heading: + ```markdown + > **SCOPE:** Entry point with project overview and navigation ONLY. + ``` + - Track violation: `scope_tag_added_claude = True` +- Read first 10 lines of docs/README.md +- Check for `` tag +- If missing: + - Use Edit tool to add SCOPE tag after version info: + ```markdown + + ``` + - Track violation: `scope_tag_added_docs_readme = True` +- Read first 10 lines of docs/principles.md +- Check for `> **SCOPE:**` or `` tag +- If missing: + - Use Edit tool to add SCOPE tag + - Track violation: `scope_tag_added_principles = True` + +**2.2 Check required sections (parametric loop)**: + +Define file parameters: +``` +files = [ + { + "path": "CLAUDE.md", + "sections": ["Documentation", "Documentation Maintenance Rules", "Maintenance"] + }, + { + "path": "docs/README.md", + "sections": ["General Documentation Standards", "Writing Guidelines", "Maintenance"] + }, + { + "path": "docs/documentation_standards.md", + "sections": ["Quick Reference", "Maintenance"] + }, + { + "path": "docs/principles.md", + "sections": ["Decision-Making Framework", "Verification Checklist", "Maintenance"] + } +] +``` + +For each file in files: +1. Read file content +2. For each required section: + - Check if `## [Section Name]` header exists + - If missing: + - Use Edit tool to add section with placeholder: + ```markdown + ## [Section Name] + + {{PLACEHOLDER}} + ``` + - Track violation: `missing_sections[file] += 1` + +**2.3 Check Maintenance sections**: +- For each file in [CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md]: + - Search for `## Maintenance` header + - If missing: + - Use Edit tool to add at end of file: + ```markdown + ## Maintenance + + **Update Triggers:** + - [To be defined] + + **Verification:** + - [ ] All links resolve to existing files + - [ ] All placeholders replaced with content + + **Last Updated:** [current date] + ``` + - Track violation: `maintenance_added[file] = True` + +**2.4 Check POSIX file endings**: +- For each file: + - Check if file ends with single blank line + - If missing: + - Use Edit tool to add final newline + - Track fix: `posix_fixed[file] = True` + +**2.5 Report validation**: +- Log summary: + ``` + ✅ Structure validation complete: + - SCOPE tags: [count] files fixed + - Missing sections: [count] sections added across [count] files + - Maintenance sections: [count] files fixed + - POSIX endings: [count] files fixed + ``` +- If violations found: "⚠️ Auto-fixed [total] structural violations" + +--- + +### Phase 3: Validate Content + +**Objective**: Ensure each file answers its questions with meaningful content. + +**Process**: + +**3.1 Load validation spec**: +- Read `references/questions.md` +- Parse questions and validation heuristics for all 4 files + +**3.2 Validate files (parametric loop)**: + +Define file parameters: +``` +files = [ + { + "path": "CLAUDE.md", + "question": "Where is project documentation located and how to navigate it?", + "heuristics": [ + "Contains link: [docs/README.md](docs/README.md)", + "Has SCOPE tag in first 10 lines", + "Contains 'Documentation Navigation Rules' section", + "Length > 80 words" + ], + "auto_discovery": ["Check package.json for name/description"] + }, + { + "path": "docs/README.md", + "question": "What is the documentation structure and what are general standards?", + "heuristics": [ + "Contains SCOPE tag", + "Has 'General Documentation Standards' section", + "Has 'Writing Guidelines' section", + "Mentions SCOPE Tags, Maintenance Sections, Sequential Numbering", + "Length > 100 words" + ], + "auto_discovery": ["Scan docs/ structure for subdirectories"] + }, + { + "path": "docs/documentation_standards.md", + "question": "What are the comprehensive documentation requirements?", + "heuristics": [ + "Contains 'Quick Reference' section with table", + "Has 12+ main sections (##)", + "File size > 300 lines", + "Mentions ISO/IEC/IEEE, DIATAXIS, arc42" + ], + "auto_discovery": [] + }, + { + "path": "docs/principles.md", + "question": "What are the development principles and decision framework?", + "heuristics": [ + "Contains SCOPE tag", + "Lists 11 principles", + "Has 'Decision-Making Framework' section", + "Has 'Verification Checklist' section", + "File size > 300 lines" + ], + "auto_discovery": [] + } +] +``` + +For each file in files: + +1. **Read file content**: + - Extract full file content + +2. **Check if content answers question**: + - Apply validation heuristics + - If ANY heuristic passes → content valid, skip to next file + - If ALL fail → content invalid, continue + +3. **Auto-discovery** (if content invalid or placeholder present): + - **CLAUDE.md**: + - Check package.json for "name" and "description" + - If found, suggest to user: "Would you like to use '{name}' and '{description}' from package.json?" + - **docs/README.md**: + - Scan docs/ directory for subdirectories (project/, reference/, tasks/) + - Generate navigation links dynamically + - **docs/documentation_standards.md**, **docs/principles.md**: + - Use template as-is (universal standards) + - No auto-discovery needed + +4. **Skip external API calls**: + - Templates already complete with universal standards + - No MCP Ref needed + +**3.3 Report content validation**: +- Log summary: + ``` + ✅ Content validation complete: + - Files checked: 4 + - Already valid: [count] + - Auto-discovery applied: [count] + - Template content used: [count] + ``` + +--- + +## Complete Output Structure + +``` +project_root/ +├── CLAUDE.md # ← Project entry point with link to docs/ +└── docs/ + ├── README.md # ← Root documentation hub (general standards) + ├── documentation_standards.md # ← Documentation requirements (60 universal requirements) + └── principles.md # ← Development principles (11 principles + Decision Framework + Verification Checklist) +``` + +**Note**: Other documentation (project/, reference/, tasks/, presentation/) created by other workers in ln-110-documents-pipeline workflow. + +--- + +## Reference Files Used + +### Templates + +**CLAUDE.md Template**: +- `references/claude_md_template.md` - Minimal CLAUDE.md with documentation link + +**Root README Template**: +- `references/docs_root_readme_template.md` (v1.1.0) - Root documentation hub with: + - Overview (documentation system organization) + - General Documentation Standards (SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions) + - Writing Guidelines (Progressive Disclosure Pattern) + - Maintenance section (Update Triggers, Verification, Last Updated) + +**Documentation Standards Template**: +- `references/documentation_standards_template.md` (v1.0.0) - Documentation requirements with: + - Quick Reference (60 universal requirements in 12 categories) + - Claude Code Integration (#26-30) + - AI-Friendly Writing Style (#31-36) + - Markdown Best Practices (#37-42) + - Code Examples Quality (#43-47) + - DIATAXIS Framework (#48-52) + - Project Files (#53-58) + - Visual Documentation (#67-71) + - Conventional Commits & Changelog (#72-75) + - Security & Compliance (#76-79) + - Performance & Optimization (#80-82) + - Project-Specific Customization Guide + - References (industry sources) + - Maintenance section + +**Development Principles Template**: +- `references/principles_template.md` (v1.0.0) - Development principles with: + - 11 Core Principles (Standards First, YAGNI, KISS, DRY, Consumer-First Design, Task Granularity, Value-Based Testing, No Legacy Code, Token Efficiency, Documentation-as-Code, Security by Design) + - Decision-Making Framework (7 steps: Security → Standards → Correctness → Simplicity → Necessity → Maintainability → Performance) + - Trade-offs (when principles conflict) + - Anti-Patterns to Avoid + - Verification Checklist (11 items) + - Maintenance section + +**Validation Specification**: +- `references/questions.md` (v1.0) - Question-driven validation: + - Questions each file must answer + - Validation heuristics + - Auto-discovery hints + +--- + +## Best Practices + +- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks) +- **Parametric validation**: Phases 2-3 use loops for 4 files (no code duplication) +- **Auto-discovery first**: Check package.json and docs/ structure before asking user +- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation) +- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT +- **CLAUDE.md**: Keep minimal - only project name, description, and docs link +- **docs/README.md**: General standards only - NO project-specific content +- **SCOPE Tags**: Include in first 3-10 lines of all documentation files + +--- + +## Prerequisites + +**Invoked by**: ln-110-documents-pipeline orchestrator + +**Requires**: None (first worker in chain) + +**Creates**: +- CLAUDE.md (project entry point) +- docs/README.md (documentation hub) +- docs/documentation_standards.md (60 requirements) +- docs/principles.md (11 principles + Decision Framework) +- Validated structure and content + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +**✅ Structure Created:** +- [ ] CLAUDE.md exists in project root +- [ ] docs/ directory exists +- [ ] docs/README.md exists +- [ ] docs/documentation_standards.md exists +- [ ] docs/principles.md exists + +**✅ Structure Validated:** +- [ ] SCOPE tags present in CLAUDE.md, docs/README.md, docs/principles.md +- [ ] Required sections present in all 4 files +- [ ] Maintenance sections present in all 4 files +- [ ] POSIX file endings compliant + +**✅ Content Validated:** +- [ ] All files checked against questions.md +- [ ] CLAUDE.md has docs link +- [ ] docs/README.md has General Standards + Writing Guidelines +- [ ] docs/documentation_standards.md has Quick Reference + 12 sections +- [ ] docs/principles.md has 11 principles + Decision Framework + Verification Checklist + +**✅ Reporting:** +- [ ] Phase 1 logged: creation summary +- [ ] Phase 2 logged: structural fixes (if any) +- [ ] Phase 3 logged: content validation (if any) + +--- + +## Technical Details + +**Standards**: +- ISO/IEC/IEEE 29148:2018 (Documentation standards) +- Progressive Disclosure Pattern (token efficiency) + +**Language**: English only + +--- + +**Version:** 10.0.0 (MAJOR: Applied ln-112 pattern - 4 phases → 3 phases, added questions.md for semantic validation, parametric validation loop, removed workflow coupling. No functionality change, pure architectural refactoring for consistency with ln-112 PoC.) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-111-root-docs-creator/diagram.html b/skills/ln-111-root-docs-creator/diagram.html new file mode 100644 index 0000000..2991751 --- /dev/null +++ b/skills/ln-111-root-docs-creator/diagram.html @@ -0,0 +1,109 @@ + + + + + + ln-111-root-docs-creator - State Diagram + + + + +
+
+

📝 ln-111-root-docs-creator

+

Root Documentation Creator - State Diagram

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Create root documentation entry points (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md)
    • +
  • Worker for: ln-110-documents-pipeline orchestrator
    • +
  • Phases: 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Semantic Content Validation)
    • +
  • Validation: Phase 2/3 validation with questions.md (22 questions for 4 documents)
    • +
  • Idempotent: Can be run multiple times safely
    • +
+
+ +
+
+
+ Creation Action +
+
+
+ Conditional Check +
+
+
+ Success State +
+
+ +
+
+graph TD + Start([Start: Root Docs Creation]) --> Phase1{CLAUDE.md exists?} + + Phase1 -->|Yes| CheckLink{Has docs/README.md
link?} + Phase1 -->|No| AskProject[Ask: Project name
and description] + + CheckLink -->|Yes| Phase2Start[Phase 2: Create docs/README.md] + CheckLink -->|No| AddLink[Add docs link
to CLAUDE.md] + + AskProject --> CreateClaude[Create CLAUDE.md
from template] + CreateClaude --> CreateStandards[Create documentation_standards.md
60 universal requirements] + CreateStandards --> CreatePrinciples[Create principles.md
11 development principles] + CreatePrinciples --> Phase2Start + AddLink --> Phase2Start + + Phase2Start --> CreateDir[Create docs/
directory] + CreateDir --> CreateReadme[Create docs/README.md
from template] + CreateReadme --> ReplaceVars[Replace placeholders:
VERSION, DATE, STATUS] + ReplaceVars --> Phase2Validate[Phase 2: Structure Validation
SCOPE tags, Maintenance sections] + Phase2Validate --> Phase3Validate[Phase 3: Semantic Content Validation
questions.md Q1-Q22] + Phase3Validate --> Notify[Notify: Root structure
established + validated] + + Notify --> End([End: ✓ 4 docs created + validated]) + + %% Styling + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px + classDef success fill:#B3E5FC,stroke:#0277BD,stroke-width:2px + + class AskProject,CreateClaude,CreateStandards,CreatePrinciples,AddLink,CreateDir,CreateReadme,ReplaceVars,Phase2Validate,Phase3Validate,Notify action + class Phase1,CheckLink decision + class End success +
+
+ +
+

🔑 Key Features

+
    +
  • First Worker: Establishes documentation structure and standards
    • +
  • Idempotent: Skips if CLAUDE.md already has docs link
    • +
  • Template-Based: Uses claude_md_template.md, docs_root_readme_template.md, documentation_standards_template.md, principles_template.md
    • +
  • General Standards: docs/README.md contains SCOPE Tags, Maintenance Sections, Writing Guidelines
    • +
  • Semantic Validation: Parametric validation loop with questions.md (Q1-Q22)
    • +
+
+ +
+

Generated for ln-111-root-docs-creator skill | Version 10.0.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-18

+
+
+ + + + diff --git a/skills/ln-111-root-docs-creator/references/claude_md_template.md b/skills/ln-111-root-docs-creator/references/claude_md_template.md new file mode 100644 index 0000000..d326ef2 --- /dev/null +++ b/skills/ln-111-root-docs-creator/references/claude_md_template.md @@ -0,0 +1,128 @@ +# {{PROJECT_NAME}} + +{{PROJECT_DESCRIPTION}} + +> **SCOPE:** Entry point with project overview and navigation ONLY. Contains project summary, documentation rules, and links to detailed docs. DO NOT add: business logic (→ Architecture.md + ADRs), principles (→ principles.md), API specs (→ api_spec.md), patterns (→ guides/). + +## ⚠️ Critical Rules for AI Agents + +**Read this table BEFORE starting any work.** + +| Category | Rule | When to Apply | Rationale | +|----------|------|---------------|-----------| +| **Standards Hierarchy** | Industry Standards → Security → Principles | All work | ISO/IEC/IEEE, RFC, OWASP override YAGNI/KISS | +| **Documentation** | Read README before folder work | Before creating/editing files | Understand structure and conventions | +| **Documentation Navigation** | Read SCOPE tag first in each document | Before reading any doc | DAG structure - understand boundaries | +| **Testing** | Read tests/README.md before tests | Before test work | Story-Level Test Task Pattern | +| **Research** | Search MCP Ref before proposing changes | Before code changes | Official docs prevent reinventing wheel | +| **Task Management** | Linear MCP only, NO gh command | All task operations | See docs/tasks/README.md | +| **Skills** | Use built-in skills proactively | Documentation/Planning/Execution | Skills automate workflows | +| **Language** | English for all content, Russian for chat | All project content | Code/docs/tasks/commits in English only | + +**Key Principles:** +- **Standards First**: Industry standards (ISO, RFC, OWASP, WCAG 2.1 AA) override development principles +- **Token Efficiency**: Progressive Disclosure Pattern (tables > paragraphs), no duplication +- **Quality**: Risk-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit per Story) +- **No Legacy Code**: Remove backward compatibility shims immediately + +--- + +## Documentation Navigation Rules + +**Graph Structure:** All documentation organized as Directed Acyclic Graph (DAG) with CLAUDE.md as entry point. + +**Reading Order:** +1. **Read SCOPE first** - Every document starts with `> **SCOPE:**` tag defining its boundaries +2. **Follow links down** - Navigate from parent to child documents through links +3. **Respect boundaries** - SCOPE tells you what IS and what IS NOT in each document + +**Example Navigation:** +``` +CLAUDE.md (SCOPE: Entry point, project overview) + → Read SCOPE: "Contains project summary, NOT implementation details" + → Need principles? Follow link → docs/principles.md + → Read SCOPE: "Contains development principles, NOT architecture" + → Need architecture? Follow link → docs/Architecture.md +``` + +--- + +## Documentation + +Project documentation: [docs/README.md](docs/README.md) + +Documentation standards: [docs/documentation_standards.md](docs/documentation_standards.md) + +Development principles: [docs/principles.md](docs/principles.md) + +## Development Commands + +| Task | Windows | Bash | +|------|---------|------| +| **Install Dependencies** | `[Add your command]` | `[Add your command]` | +| **Run Tests** | `[Add your command]` | `[Add your command]` | +| **Start Dev Server** | `[Add your command]` | `[Add your command]` | +| **Build** | `[Add your command]` | `[Add your command]` | +| **Lint/Format** | `[Add your command]` | `[Add your command]` | + +> [!NOTE] + +> Update this table with project-specific commands during project setup + +--- + +## Documentation Maintenance Rules + +### For AI Agents (Claude Code) + +**Principles:** +1. **Single Source of Truth:** Each fact exists in ONE place only - link, don't duplicate +2. **Graph Structure:** All docs reachable from `CLAUDE.md` → `docs/README.md` (DAG, no cycles) +3. **SCOPE Tag Required:** Every document MUST start with `> **SCOPE:**` tag defining boundaries (what IS and what IS NOT in document) +4. **DRY (Don't Repeat Yourself):** Reference existing docs instead of copying content +5. **Update Immediately:** When code changes, update related docs while context is fresh +6. **Context-Optimized:** Keep `CLAUDE.md` concise (≤100 lines recommended) - detailed info in `docs/` +7. **English Only:** ALL project content (code, comments, documentation, tasks, commit messages, variable names) MUST be in English + +For document responsibilities and scope, see [docs/README.md](docs/README.md). + +**Avoiding Duplication:** + +**BAD:** +- Same architecture description in 3 files +- Development commands duplicated in multiple docs +- Full specs repeated across multiple guides + +**GOOD:** +- `CLAUDE.md`: "See [docs/project/architecture.md](docs/project/architecture.md) for component structure (C4 diagrams)" +- Guides reference each other: "See [guide_name.md](./guide_name.md)" +- One canonical source per concept with links from other docs + +**Best Practices (Claude Code 2025):** +- Use subagents for complex doc updates to avoid context pollution +- Update docs immediately after feature completion (context is fresh) +- Use `/clear` after big doc refactors to start fresh +- Keep `CLAUDE.md` as the always-loaded entry point with links to detailed docs + +--- + +## Maintenance + +**Update Triggers:** +- When changing project navigation (new/renamed docs) +- When updating critical rules for agents +- When modifying development commands +- When adding/removing key principles +- When documentation structure changes + +**Verification:** +- [ ] All links resolve to existing files +- [ ] SCOPE tag clearly defines document boundaries +- [ ] Critical rules align with project requirements +- [ ] Command examples match actual project setup +- [ ] No duplicated content across documents +- [ ] Documentation Standards link correct + +--- + +**Last Updated:** {{DATE}} diff --git a/skills/ln-111-root-docs-creator/references/docs_root_readme_template.md b/skills/ln-111-root-docs-creator/references/docs_root_readme_template.md new file mode 100644 index 0000000..294d23e --- /dev/null +++ b/skills/ln-111-root-docs-creator/references/docs_root_readme_template.md @@ -0,0 +1,224 @@ +# Documentation System + +**Version:** {{VERSION}} +**Last Updated:** {{DATE}} +**Status:** {{STATUS}} + + + + +--- + +## Overview + +This documentation system provides comprehensive technical and operational documentation following industry standards (ISO/IEC/IEEE 29148, arc42, C4 Model, Michael Nygard's ADR format). + +**Documentation is organized into three main areas:** +- **Project Documentation** - Requirements, architecture, technical specifications +- **Reference Documentation** - Architecture decisions (ADRs), reusable patterns (Guides), API references (Manuals) +- **Task Management** - Linear workflow, task tracking rules, kanban board + +--- + +## General Documentation Standards + +All documentation in this system follows these conventions: + +### SCOPE Tags + +Every document contains HTML comment tags defining its boundaries: + +```html + + +``` + +**Purpose**: Prevent content duplication, maintain single source of truth, redirect to correct location. + +**Example**: +```html + + +``` + +### Maintenance Sections + +All documents contain a **Maintenance** section with: + +| Field | Description | Example | +|-------|-------------|---------| +| **Update Triggers** | When to update the document | "When changing acceptance criteria (Non-Functional Requirements are forbidden here)" | +| **Verification** | How to verify document is current | "Check all FR-XXX IDs referenced in tests exist" | +| **Last Updated** | Date of last modification | "2025-11-15" | + +### Sequential Numbering + +**Rule**: Phases/Sections/Steps use sequential integers: 1, 2, 3, 4 (NOT 1, 1.5, 2). + +**Exceptions**: + +| Case | Format | Example | When Valid | +|------|--------|---------|------------| +| **Conditional Branching** | Letter suffixes | Phase 4a (CREATE), Phase 4b (REPLAN), Phase 5 | Mutually exclusive paths (EITHER A OR B) | +| **Loop Internals** | Steps inside Phase | Phase 3: Loop → Step 1 → Step 2 → Repeat | Cyclic workflows with repeated sub-steps | + +**Important**: When inserting new items, renumber all subsequent items. + +### Placeholder Conventions + +Documents use placeholders for registry updates: + +| Placeholder | Location | Purpose | Updated By | +|-------------|----------|---------|------------| +| `{{ADR_LIST}}` | reference/README.md | ADR registry | ln-322-adr-creator | +| `{{GUIDE_LIST}}` | reference/README.md | Guide registry | ln-321-guide-creator | +| `{{MANUAL_LIST}}` | reference/README.md | Manual registry | ln-323-manual-creator | + +**Usage**: Skills automatically add new entries BEFORE the placeholder using Edit tool. + +### Writing Guidelines (Progressive Disclosure Pattern) + +All documentation follows token-efficient formatting rules: + +| Content Type | Format | Rationale | +|--------------|--------|-----------| +| **Skill descriptions** | < 200 chars in SKILL.md frontmatter | Clarity, focused scope | +| **Workflows** | Reference table with link to SKILL.md | Avoid duplication (DRY) | +| **Examples** | Table rows (verdict + rationale) | 60-80% more compact than paragraphs | +| **Lists** | Bullet points with inline details | Progressive disclosure | +| **References** | One-line format (source - topics - insight) | Scannable, no verbose paragraphs | +| **Comparisons** | Table with columns | Visual clarity, easy scanning | +| **Step-by-step processes** | Inline arrow notation (Step 1 → Step 2 → Step 3) | Compact flow representation | + +**Verbose content is justified for:** +- ❌ Anti-patterns (educational value - prevents mistakes) +- 🎓 Complex architectural explanations (orchestrator patterns, state machines) +- ⚠️ Critical rules with rationale (INVEST criteria, task sizing) + +**Compression targets:** +- Main documentation files: < 500 lines (optimal: 300-400 lines) +- README hubs: < 200 lines +- Individual guides: < 800 lines (optimal: 400-600 lines) + +### Documentation Standards + +**Full documentation requirements:** See [documentation_standards.md](documentation_standards.md) + +Key highlights: +- **Claude Code Integration** - CLAUDE.md ≤100 lines, @-sourcing, sessionStart hooks +- **AI-Friendly Writing** - Second person, active voice, max 25 words/sentence +- **Code Examples** - All examples runnable, realistic names, show expected output +- **DIATAXIS Framework** - Organize docs into Tutorial/How-to/Reference/Explanation +- **Security** - Never commit secrets, use .env.example templates +- **Conventional Commits** - Structured commit messages for auto-changelog + +**Total:** 60 requirements in 12 categories. See documentation_standards.md for complete details. + +--- + +## Documentation Structure + +### 1. [Project Documentation](project/README.md) + +Core project documentation created by ln-114-project-docs-creator skill: + +- **[README.md](project/README.md)** - Project documentation hub +- **[requirements.md](project/requirements.md)** - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization +- **[architecture.md](project/architecture.md)** - System architecture (C4 Model, arc42) +- **[technical_specification.md](project/technical_specification.md)** - Implementation details + +**Purpose**: Define WHAT we build and WHY. + +**Created by**: ln-114-project-docs-creator + +--- + +### 2. [Reference Documentation](reference/README.md) + +Reusable knowledge base and architecture decisions: + +- **[ADRs](reference/adrs/)** - Architecture Decision Records (format: `adr-NNN-slug.md`) +- **[Guides](reference/guides/)** - Project patterns and best practices (format: `NN-pattern-name.md`) +- **[Manuals](reference/manuals/)** - Package API references (format: `package-version.md`) + +**Purpose**: Document HOW we build (patterns, decisions, APIs). + +**Created by**: ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator + +--- + +### 3. [Task Management System](tasks/README.md) + +Linear integration and workflow rules: + +- **[README.md](tasks/README.md)** - Task lifecycle, Linear integration rules, workflow skills +- **[kanban_board.md](tasks/kanban_board.md)** - Live navigation to active tasks + +**Purpose**: Define HOW we track and manage work. + +**Created by**: ln-111-docs-creator (Phase 2, Phase 9-10) + +--- + +## Standards Compliance + +This documentation system follows: + +| Standard | Application | Reference | +|----------|-------------|-----------| +| **ISO/IEC/IEEE 29148:2018** | Requirements Engineering | [requirements.md](project/requirements.md) | +| **ISO/IEC/IEEE 42010:2022** | Architecture Description | [architecture.md](project/architecture.md) | +| **arc42 Template** | Software architecture documentation | [architecture.md](project/architecture.md) | +| **C4 Model** | Software architecture visualization | [architecture.md](project/architecture.md) | +| **Michael Nygard's ADR Format** | Architecture Decision Records | [reference/adrs/](reference/adrs/) | +| **MoSCoW Prioritization** | Requirements prioritization | [requirements.md](project/requirements.md) | + +--- + +## Contributing to Documentation + +When updating documentation: + +1. **Check SCOPE tags** at top of document to ensure changes belong there +2. **Update Maintenance > Last Updated** date in the modified document +3. **Update registry** if adding new documents: + - ADRs, Guides, Manuals → automatically updated by skills + - Project docs → update [project/README.md](project/README.md) manually +4. **Follow sequential numbering** rules (no decimals unless conditional branching) +5. **Add placeholders** if creating new document types +6. **Verify links** after structural changes + +--- + +## Quick Navigation + +| Area | Key Documents | Skills | +|------|---------------|--------| +| **Standards** | [documentation_standards.md](documentation_standards.md) | ln-111-root-docs-creator, ln-121-structure-validator | +| **Project** | [requirements.md](project/requirements.md), [architecture.md](project/architecture.md), [technical_specification.md](project/technical_specification.md) | ln-114-project-docs-creator, ln-122-content-updater | +| **Reference** | [ADRs](reference/adrs/), [Guides](reference/guides/), [Manuals](reference/manuals/) | ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator | +| **Tasks** | [kanban_board.md](tasks/kanban_board.md), [README.md](tasks/README.md) | ln-210-epic-coordinator, ln-220-story-coordinator, ln-310-story-decomposer | + +--- + +## Maintenance + +**Update Triggers**: +- When adding new documentation areas (new subdirectories) +- When changing general documentation standards (SCOPE, Maintenance, Sequential Numbering) +- When changing writing guidelines or documentation formatting standards +- When adding new placeholder conventions +- When updating compliance standards + +**Verification**: +- All links to subdirectory READMEs are valid +- SCOPE tags accurately reflect document boundaries +- Placeholder conventions documented for all registries +- Standards Compliance table references correct documents + +**Last Updated**: {{DATE}} + +--- + +**Template Version:** 1.1.0 +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-111-root-docs-creator/references/documentation_standards_template.md b/skills/ln-111-root-docs-creator/references/documentation_standards_template.md new file mode 100644 index 0000000..d8b141d --- /dev/null +++ b/skills/ln-111-root-docs-creator/references/documentation_standards_template.md @@ -0,0 +1,160 @@ +# Documentation Standards + +**Comprehensive Requirements for Claude Code Skills Documentation (2024-2025)** + +**Last Updated:** {{DATE}} + + + +--- + +## Quick Reference (82 Requirements) + +**Legend:** 🔴 Critical | 🟡 Important | 🟢 Desired | ⚠️ Conditional | ✅ Already implemented + +| Category | Count | 🔴 | 🟡 | 🟢 | ⚠️ | ✅ | Validator | +|----------|-------|-----|-----|-----|-----|-----|-----------| +| **Core Documentation** | 25 | 8 | 12 | 5 | 0 | 0 | ln-121, ln-122 | +| **Claude Code Integration** | 5 | 1 | 2 | 2 | 0 | 0 | ln-121 v2.1.0+ | +| **AI-Friendly Writing** | 6 | 0 | 5 | 1 | 0 | 0 | ln-121 warning | +| **Markdown Best Practices** | 6 | 0 | 4 | 2 | 0 | 0 | ln-121 v2.1.0+ | +| **Code Examples Quality** | 5 | 1 | 2 | 2 | 0 | 0 | Manual + CI | +| **DIATAXIS Framework** | 5 | 0 | 1 | 2 | 0 | 2 | Manual | +| **Project Files** | 6 | 1 | 3 | 2 | 0 | 0 | Manual | +| **Quality Checks** | 5 | 0 | 4 | 1 | 0 | 0 | markdownlint, Vale | +| **Front Matter (SSG)** | 3 | 0 | 0 | 2 | 1 | 0 | Conditional | +| **Visual Documentation** | 5 | 0 | 0 | 4 | 0 | 1 | Manual | +| **Conventional Commits** | 4 | 0 | 1 | 1 | 0 | 2 | commitlint | +| **Security & Compliance** | 4 | 1 | 3 | 0 | 0 | 0 | Manual | +| **Performance** | 3 | 0 | 1 | 2 | 0 | 0 | Manual | + +**Total:** 82 requirements | 🔴 12 Critical | 🟡 38 Important | 🟢 24 Desired | ⚠️ 1 Conditional | ✅ 5 Implemented + +--- + +## Key Requirements by Priority + +### Critical (Must Have) + +| Requirement | Rationale | Validator | +|------------|-----------|-----------| +| CLAUDE.md ≤100 lines | Claude Code performance optimization | ln-121 v2.1.0+ | +| All code examples runnable | Prevent documentation drift | Manual + CI | +| LICENSE file exists | Legal compliance | Manual | +| Never commit secrets | Security breach prevention | Manual | + +### Important (Should Have) + +**Claude Code Integration:** +- @-sourcing support in CLAUDE.md (DRY pattern) +- Explicitly specify `setting_sources=["project"]` + +**AI-Friendly Writing:** +- Use second person ("you" vs "users") +- Active voice instead of passive +- Short sentences (max 25 words) +- Prohibited phrases ("please note", "simply", "just", "easily") +- Don't assume prior knowledge + +**Markdown Best Practices:** +- Header depth ≤ h3 (rarely h4) +- Descriptive links (not "click here") +- Callouts/Admonitions for important info +- Files end with single blank line (POSIX) + +**Code Examples Quality:** +- Test documentation examples in CI/CD +- Include setup context (directory, prerequisites) + +**Project Files:** +- CONTRIBUTING.md (contribution process) +- SECURITY.md (vulnerability reporting) +- .gitignore for docs (exclude generated files) + +**Quality Checks:** +- markdownlint-cli2 (.markdownlint.jsonc) +- Vale.sh (.vale.ini for editorial checks) +- Build verification (prevent broken deployments) +- Link checking (dead link detection) + +**Security & Compliance:** +- GitHub Secrets for CI/CD +- .env.example instead of .env +- Vulnerability reporting process (SECURITY.md) + +**Performance:** +- Optimize CLAUDE.md size (-30 to -40% tokens via @-sourcing) + +### Desired (Nice to Have) + +**Documentation Structure:** DIATAXIS framework (Tutorial/How-to/Reference/Explanation sections), How-to guides ✅, Reference docs ✅ + +**Visual Elements:** Mermaid diagrams ✅, workflow diagrams, sequence diagrams, light/dark theme support, centralized image storage + +**Version Control:** Conventional Commits format, auto-generate CHANGELOG, Keep a Changelog ✅, Semantic versioning ✅ + +**Code Quality:** Realistic variable names (not foo/bar), show expected output, code blocks in step lists + +**Project Files:** CODE_OF_CONDUCT.md, README badges, vocabulary files for terminology + +**Advanced Features:** SessionStart hooks, subagents in .claude/agents/*.md, Front Matter for SSG (Hugo/Docusaurus) ⚠️, lazy loading, caching strategy + +**Writing Style:** Avoid first-person pronouns, Title case for h1/Sentence case for h2+ + +--- + +## Standards Compliance + +| Standard | Reference | +|----------|-----------| +| **ISO/IEC/IEEE 29148:2018** | Requirements Engineering | +| **ISO/IEC/IEEE 42010:2022** | Architecture Description | +| **DIATAXIS Framework** | diataxis.fr - Documentation structure | +| **RFC 2119, WCAG 2.1 AA** | Requirement keywords, Accessibility | +| **OWASP Top 10** | Security requirements | +| **Conventional Commits** | conventionalcommits.org | +| **Keep a Changelog** | Changelog format | +| **Semantic Versioning** | Major.Minor.Patch | + +**Sources:** Claude Code docs, Clever Cloud guide, DIATAXIS framework, Matter style guide + +--- + +## Verification Checklist + +Before submitting documentation: + +- [ ] **CLAUDE.md ≤100 lines** - Concise and focused +- [ ] **All code examples runnable** - No placeholders, tested +- [ ] **LICENSE file exists** - Legal compliance +- [ ] **No secrets committed** - API keys in .env only +- [ ] **Header depth ≤ h3, files end with blank line** - Markdown standards +- [ ] **Active voice, second person, short sentences** - AI-friendly writing +- [ ] **SCOPE tag in docs/**, Maintenance section** - Core requirements +- [ ] **Descriptive links, callouts for important info** - Best practices + +--- + +## Maintenance + +**Update Triggers:** +- When Claude Code releases new best practices +- When industry standards evolve (ISO/IEC/IEEE updates) +- When new validation tools become available +- When ln-121-structure-validator or ln-122-content-updater add new checks +- Annual review (Q1 each year) + +**Verification:** +- [ ] All 82 requirements documented with rationale +- [ ] Priority levels assigned (Critical/Important/Desired) +- [ ] Validators identified for automated checks +- [ ] Standards compliance table complete +- [ ] References link to authoritative sources +- [ ] Verification checklist covers all critical requirements + +**Last Updated:** {{DATE}} + +--- + +**Template Version:** 2.0.0 (MAJOR: Progressive Disclosure - reduced from 390→160 lines (-59%), removed detailed sections 1-12 and Implementation Roadmap, converted to compact table format, added SCOPE tag) +**Template Last Updated:** {{DATE}} diff --git a/skills/ln-111-root-docs-creator/references/principles_template.md b/skills/ln-111-root-docs-creator/references/principles_template.md new file mode 100644 index 0000000..6b68629 --- /dev/null +++ b/skills/ln-111-root-docs-creator/references/principles_template.md @@ -0,0 +1,110 @@ +# Development Principles + +**Last Updated:** {{DATE}} + + + +--- + +## Core Principles + +| # | Name | Type | Principle | Approach/Rules | +|---|------|------|-----------|----------------| +| **1** | **Standards First** | code+docs | Industry standards (ISO/RFC/OWASP/WCAG) override development principles | **Hierarchy:** Industry Standards → Security Standards → Accessibility Standards → Dev Principles (YAGNI/KISS/DRY within standard boundaries) | +| **2** | **YAGNI (You Aren't Gonna Need It)** | code+docs | Don't build features "just in case". Build what's needed NOW | **Avoid:** Generic frameworks for one use case, caching without bottleneck, extensibility points without requirements | +| **3** | **KISS (Keep It Simple)** | code+docs | Simplest solution that solves the problem. No unnecessary complexity | **Approach:** Start with naive solution → Add complexity ONLY when proven necessary → Each abstraction layer must justify existence | +| **4** | **DRY (Don't Repeat Yourself)** | code+docs | Each piece of knowledge exists in ONE place. Link, don't duplicate | **Code:** Extract repeated logic, constants defined once. **Docs:** Single Source of Truth, reference via links, update immediately | +| **5** | **Consumer-First Design** | code | Design APIs/functions/workflows from consumer's perspective | **Design:** 1. Define interface/API FIRST (what consumers need) → 2. Implement internals SECOND (how it works) → 3. Never expose internal complexity to consumers. **Note:** This is for API/interface DESIGN, not task execution order (see Foundation-First Execution in workflow) | +| **6** | **No Legacy Code** | code | Remove backward compatibility shims immediately after migration | **Rules:** Deprecated features deleted in NEXT release (not "someday"), NO commented-out code (use git history), NO `if legacy_mode:` branches | +| **7** | **Documentation-as-Code** | docs | Documentation lives WITH code, updated WITH code changes | **Rules:** Documentation in same commit as code, NO separate "docs update" tasks, Outdated docs = bug (same severity as code bug) | +| **8** | **Security by Design** | code | Security integrated from design phase, not bolted on later | **Practices:** Never commit secrets → env vars/secret managers, Validate at boundaries → Pydantic models, Least Privilege → minimum permissions, Fail Securely → don't leak info in errors, Defense in Depth → multiple security layers | + +--- + +## Decision-Making Framework + +When making technical decisions, evaluate against these principles **in order**: + +1. **Security:** Is it secure by design? (OWASP, NIST standards) +2. **Standards Compliance:** Does it follow industry standards? (ISO, RFC, W3C) +3. **Correctness:** Does it solve the problem correctly? +4. **Simplicity (KISS):** Is it the simplest solution that works? +5. **Necessity (YAGNI):** Do we actually need this now? +6. **Maintainability:** Can future developers understand and modify it? +7. **Performance:** Is it fast enough? (Optimize only if proven bottleneck) + +### Trade-offs + +When principles conflict, use the Decision-Making Framework hierarchy: + +| Conflict | Lower Priority | Higher Priority | Resolution | +|----------|---------------|-----------------|------------| +| **Simplicity vs Security** | KISS | Security by Design | Choose secure solution, even if more complex | +| **YAGNI vs Standards** | YAGNI | Standards First | Implement standard now (e.g., OAuth 2.0), not "simple custom auth" | +| **Flexibility vs Constraints** | Flexibility | YAGNI | Choose constraints (clear boundaries), not open-ended "for future" | + +--- + +## Anti-Patterns to Avoid + +### God Objects +- ❌ One class/module that does everything +- ✅ Small, focused classes with single responsibility + +### Premature Optimization +- ❌ Caching before measuring actual bottlenecks +- ✅ Measure first (profiling, metrics), optimize proven bottlenecks + +### Over-Engineering +- ❌ Complex abstractions "for future flexibility" +- ✅ Simple solution now, refactor if complexity justified later + +### Magic Numbers/Strings +- ❌ `if status == 200:` hardcoded everywhere +- ✅ `if status == HTTPStatus.OK:` or `STATUS_OK = 200` as constant + +### Leaky Abstractions +- ❌ Service layer exposes database models to API layer +- ✅ Service layer returns DTOs/Pydantic schemas, hides ORM details + +--- + +## Verification Checklist + +Before submitting code, verify compliance with principles: + +- [ ] **Standards First:** Follows industry standards (ISO, RFC, OWASP, WCAG 2.1 AA) +- [ ] **YAGNI:** Only building what's needed now (no speculative features) +- [ ] **KISS:** Solution is as simple as possible, not simpler +- [ ] **DRY:** No duplicated logic or documentation +- [ ] **Consumer-First Design:** API/interface designed from consumer perspective +- [ ] **No Legacy Code:** No deprecated code, no commented-out code +- [ ] **Documentation-as-Code:** Docs updated in same commit as code +- [ ] **Security by Design:** No secrets committed, input validated, least privilege + +--- + +## Maintenance + +**Update Triggers:** +- When adding new principles +- When changing decision framework hierarchy +- When industry standards evolve (ISO, RFC, OWASP updates) +- When trade-off examples change +- Annual review (Q1 each year) + +**Verification:** +- [ ] All 8 principles documented +- [ ] Decision Framework clear (7 steps) +- [ ] Trade-offs explained (3 conflicts) +- [ ] Anti-patterns listed (5 patterns) +- [ ] Verification Checklist complete (8 items) +- [ ] Links to external resources valid +- [ ] Table format demonstrates principles clearly + +**Last Updated:** {{DATE}} + +--- + +**Template Version:** 3.0.0 (MAJOR: Removed domain-specific principles (Task Granularity→ln-113, Value-Based Testing→ln-116, Token Efficiency→documentation_standards.md), converted to table format (8 universal principles only), removed all detailed sections with examples for Progressive Disclosure) +**Template Last Updated:** {{DATE}} diff --git a/skills/ln-111-root-docs-creator/references/questions.md b/skills/ln-111-root-docs-creator/references/questions.md new file mode 100644 index 0000000..fce414c --- /dev/null +++ b/skills/ln-111-root-docs-creator/references/questions.md @@ -0,0 +1,475 @@ +# Root Documentation Questions + +**Purpose:** Define what each root documentation file should answer. Each section maps explicitly to document sections for validation. + +**Format:** Document → Rules → Questions (with target sections) → Validation Heuristics → Auto-Discovery + +--- + +## Table of Contents + +| Document | Questions | Auto-Discovery | Priority | Line | +|----------|-----------|----------------|----------|------| +| [CLAUDE.md](#claudemd) | 6 | Medium | Critical | L30 | +| [docs/README.md](#docsreadmemd) | 7 | Low | High | L170 | +| [docs/documentation_standards.md](#docsdocumentation_standardsmd) | 3 | None | Medium | L318 | +| [docs/principles.md](#docsprinciplesmd) | 6 | None | High | L381 | + +**Priority Legend:** +- **Critical:** Must answer all questions +- **High:** Strongly recommended +- **Medium:** Optional (can use template defaults) + +**Auto-Discovery Legend:** +- **None:** No auto-discovery needed (use template as-is) +- **Low:** 1-2 questions need auto-discovery +- **Medium:** 3+ questions need auto-discovery + +--- + + +## CLAUDE.md + +**File:** CLAUDE.md (project root) +**Target Sections:** ⚠️ Critical Rules for AI Agents, Documentation Navigation Rules, Documentation, Development Commands, Documentation Maintenance Rules, Maintenance + +**Rules for this document:** +- Recommended length: ≤100 lines (guideline from Claude Code docs) +- Must have SCOPE tag in first 10 lines +- Must link to docs/README.md +- Entry point for all documentation (DAG root) + +--- + + +### Question 1: Where is project documentation located? + +**Expected Answer:** Links to docs/README.md, documentation_standards.md, principles.md +**Target Section:** ## Documentation + +**Validation Heuristics:** +- ✅ Has section "## Documentation" with links to docs/README.md, documentation_standards.md, principles.md + +**Auto-Discovery:** +- None needed (standard structure) + + +--- + + +### Question 2: What are critical rules for AI agents? + +**Expected Answer:** Table of critical rules organized by category (Standards Hierarchy, Documentation, Testing, Research, Task Management, Skills, Language) with When to Apply and Rationale columns +**Target Section:** ## ⚠️ Critical Rules for AI Agents + +**Validation Heuristics:** +- ✅ Has section "## ⚠️ Critical Rules for AI Agents" with table (Category, Rule, When to Apply, Rationale), 7+ rows, "Key Principles" subsection, mentions Standards First, Token Efficiency, Quality, No Legacy Code + +**Auto-Discovery:** +- None needed (universal rules) + + +--- + + +### Question 3: How to navigate documentation (DAG structure)? + +**Expected Answer:** SCOPE tags explanation + reading order + graph structure with examples +**Target Section:** ## Documentation Navigation Rules + +**Validation Heuristics:** +- ✅ Has section "## Documentation Navigation Rules" with SCOPE tag explanation, reading order (numbered list), example navigation, >40 words + +**Auto-Discovery:** +- None needed (universal best practice) + + +--- + + +### Question 4: What are documentation maintenance rules? + +**Expected Answer:** DRY principles, Single Source of Truth, update triggers, English-only policy +**Target Section:** ## Documentation Maintenance Rules + +**Validation Heuristics:** +- ✅ Has section "## Documentation Maintenance Rules" with "Single Source of Truth"/"DRY", "English Only" rule, "Principles"/"Avoiding Duplication" subsections, >60 words + +**Auto-Discovery:** +- None needed (universal standards) + + +--- + + +### Question 5: When should CLAUDE.md be updated? + +**Expected Answer:** Update triggers + verification checklist +**Target Section:** ## Maintenance + +**Validation Heuristics:** +- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections, "Last Updated" field + +**Auto-Discovery:** +- None needed (standard maintenance section) + + +--- + + +### Question 6: What are the project development commands? + +**Expected Answer:** Table with development commands organized by task (Install Dependencies, Run Tests, Start Dev Server, Build, Lint/Format) for both Windows and Bash +**Target Section:** ## Development Commands + +**Validation Heuristics:** +- ✅ Has section "## Development Commands" with table (Task, Windows, Bash), 5+ rows, note about updating commands, placeholder/actual commands + +**Auto-Discovery:** +- Scan package.json → "scripts" field (for Node.js projects) +- Scan pyproject.toml → [tool.poetry.scripts] or [project.scripts] (for Python projects) +- Scan Makefile → targets (for Make-based projects) +- Scan composer.json → "scripts" field (for PHP projects) + +**Notes:** +- If no commands found, use placeholder: `[Add your command]` +- Auto-discovery hints can suggest common commands based on detected project type + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tag in first 10 lines +- ✅ Total length > 80 words (meaningful content) + +**Auto-Discovery Hints:** +- Scan package.json → "name", "description" fields (for project name/description) +- Check existing CLAUDE.md for project name + + + +--- + + +## docs/README.md + +**File:** docs/README.md (documentation hub) +**Target Sections:** Overview, General Documentation Standards, Writing Guidelines, Standards Compliance, Contributing to Documentation, Quick Navigation, Maintenance + +**Rules for this document:** +- Must have SCOPE tag in first 10 lines (HTML comment) +- Hub file - navigation to subdirectories (project/, reference/, tasks/) +- General standards only - NO project-specific content + +--- + + +### Question 1: What is the documentation structure? + +**Expected Answer:** Overview of documentation areas (Project, Reference, Task Management) +**Target Section:** ## Overview + +**Validation Heuristics:** +- ✅ Has section "## Overview" mentioning Project Documentation (project/), Reference Documentation (reference/), Task Management (tasks/), >30 words + +**Auto-Discovery:** +- Scan docs/ directory for subdirectories (project/, reference/, tasks/) + + +--- + + +### Question 2: What are general documentation standards? + +**Expected Answer:** SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions +**Target Section:** ## General Documentation Standards + +**Validation Heuristics:** +- ✅ Has section "## General Documentation Standards" with subsections (SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions), >100 words + +**Auto-Discovery:** +- None needed (universal standards) + + +--- + + +### Question 3: What are writing guidelines? + +**Expected Answer:** Progressive Disclosure Pattern, token efficiency, table-first format +**Target Section:** ## Writing Guidelines + +**Validation Heuristics:** +- ✅ Has section "## Writing Guidelines" mentioning Progressive Disclosure/token efficiency, table/list with format guidelines, >50 words + +**Auto-Discovery:** +- None needed (universal best practice) + + +--- + + +### Question 4: When should docs/README.md be updated? + +**Expected Answer:** Update triggers + verification checklist +**Target Section:** ## Maintenance + +**Validation Heuristics:** +- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections + +**Auto-Discovery:** +- None needed (standard maintenance section) + + +--- + + +### Question 5: What are the standards this documentation complies with? + +**Expected Answer:** Standards Compliance table with Standard, Application, and Reference columns +**Target Section:** ## Standards Compliance + +**Validation Heuristics:** +- ✅ Has section "## Standards Compliance" with table (Standard, Application, Reference), 5+ standards (ISO/IEC/IEEE 29148:2018, ISO/IEC/IEEE 42010:2022, arc42, C4 Model, ADR Format, MoSCoW), document path links + +**Auto-Discovery:** +- None needed (universal standards) + + +--- + + +### Question 6: How to contribute to documentation? + +**Expected Answer:** Numbered list of contribution steps (Check SCOPE tags, Update Last Updated date, Update registry, Follow sequential numbering, Add placeholders, Verify links) +**Target Section:** ## Contributing to Documentation + +**Validation Heuristics:** +- ✅ Has section "## Contributing to Documentation" with 6+ steps mentioning SCOPE tags, Last Updated, registry, sequential numbering, link verification, >40 words + +**Auto-Discovery:** +- None needed (universal contribution guidelines) + + +--- + + +### Question 7: How to quickly navigate to key documentation areas? + +**Expected Answer:** Quick Navigation table with Area, Key Documents, and Skills columns +**Target Section:** ## Quick Navigation + +**Validation Heuristics:** +- ✅ Has section "## Quick Navigation" with table (Area, Key Documents, Skills), 4 rows (Standards, Project, Reference, Tasks), document/skill name links + +**Auto-Discovery:** +- Scan docs/ directory structure (project/, reference/, tasks/) +- Detect skill references from kanban_board.md (if exists) + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tag (HTML comment) in first 10 lines +- ✅ Total length > 100 words + + + +--- + + +## docs/documentation_standards.md + +**File:** docs/documentation_standards.md (60 universal requirements) +**Target Sections:** Quick Reference, 12 main sections (Claude Code Integration through References), Maintenance + +**Rules for this document:** +- 60+ universal documentation requirements +- 12 main sections covering industry standards +- References to ISO/IEC/IEEE, DIATAXIS, arc42 + +--- + + +### Question 1: What are the comprehensive documentation requirements? + +**Expected Answer:** Quick Reference table with 60+ requirements in 12 categories +**Target Section:** ## Quick Reference + +**Validation Heuristics:** +- ✅ Has section "## Quick Reference" with table (Requirement, Description, Priority, Reference), 60+ rows across categories (Claude Code Integration, AI-Friendly Writing, Markdown, Code Examples, DIATAXIS) + +**Auto-Discovery:** +- None needed (universal standards, use template as-is) + + +--- + + +### Question 2: What are the detailed requirements for each category? + +**Expected Answer:** 12 main sections with detailed explanations +**Target Sections:** 12 sections (## Claude Code Integration, ## AI-Friendly Writing Style, etc.) + +**Validation Heuristics:** +- ✅ Has 12+ main sections with subsections, mentions ISO/IEC/IEEE/DIATAXIS/arc42 standards, >300 lines + +**Auto-Discovery:** +- None needed (universal standards) + + +--- + + +### Question 3: When should documentation standards be updated? + +**Expected Answer:** Update triggers + verification checklist +**Target Section:** ## Maintenance + +**Validation Heuristics:** +- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections + +**Auto-Discovery:** +- None needed (standard maintenance section) + + +--- + +**Overall File Validation:** +- ✅ File size > 300 lines +- ✅ Mentions ISO/IEC/IEEE 29148:2018 +- ✅ Mentions DIATAXIS framework +- ✅ Mentions arc42 + +**MCP Ref Hints:** +- Research: "DIATAXIS framework documentation" (if user wants customization) +- Research: "ISO/IEC/IEEE 29148:2018" (if user wants compliance details) + + + +--- + + +## docs/principles.md + +**File:** docs/principles.md (8 development principles + Decision Framework) +**Target Sections:** Core Principles table, Decision-Making Framework, Trade-offs (subsection), Anti-Patterns, Verification Checklist, Maintenance + +**Rules for this document:** +- Must have SCOPE tag in first 10 lines +- 8 core principles (Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design) +- Decision-Making Framework (7 steps) +- Verification Checklist (8 items) + +--- + + +### Question 1: What are the core development principles? + +**Expected Answer:** 8 principles in table format (4 columns: Name, Type, Principle, Approach/Rules) +**Target Section:** ## Core Principles + +**Validation Heuristics:** +- ✅ Has section "## Core Principles" with 8-row table (Name, Type, Principle, Approach/Rules): Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design, no subsections + +**Auto-Discovery:** +- None needed (universal principles) + +**Notes:** +- Task Granularity → Moved to ln-113-tasks-docs-creator (task management specific) +- Value-Based Testing → Moved to ln-116-test-docs-creator (testing specific) +- Token Efficiency → Referenced in documentation_standards.md (already detailed in #80-85) + + +--- + + +### Question 2: How to make decisions when principles conflict? + +**Expected Answer:** Decision-Making Framework with priority order (Security → Standards → Correctness → ...) +**Target Section:** ## Decision-Making Framework + +**Validation Heuristics:** +- ✅ Has section "## Decision-Making Framework" with 7 steps (Security, Standards, Correctness, Simplicity, Necessity, Maintainability, Performance), >30 words + +**Auto-Discovery:** +- None needed (universal framework) + + +--- + + +### Question 3: How to resolve conflicts when principles contradict? + +**Expected Answer:** Trade-offs table with Conflict, Lower Priority, Higher Priority, and Resolution columns +**Target Section:** ### Trade-offs (subsection under Decision-Making Framework) + +**Validation Heuristics:** +- ✅ Has subsection "### Trade-offs" under Decision-Making Framework with table (Conflict, Lower Priority, Higher Priority, Resolution), 3+ conflicts using framework hierarchy + +**Auto-Discovery:** +- None needed (universal trade-offs) + + +--- + + +### Question 4: What are common anti-patterns to avoid? + +**Expected Answer:** List of anti-patterns across principles +**Target Section:** ## Anti-Patterns to Avoid + +**Validation Heuristics:** +- ✅ Has section "## Anti-Patterns to Avoid" with 5+ anti-patterns, >20 words + +**Auto-Discovery:** +- None needed (universal anti-patterns) + + +--- + + +### Question 5: How to verify principles compliance? + +**Expected Answer:** Verification checklist with 8 items +**Target Section:** ## Verification Checklist + +**Validation Heuristics:** +- ✅ Has section "## Verification Checklist" with 8-item checklist (- [ ] format) covering all 8 core principles + +**Auto-Discovery:** +- None needed (universal checklist) + + +--- + + +### Question 6: When should principles be updated? + +**Expected Answer:** Update triggers + verification +**Target Section:** ## Maintenance + +**Validation Heuristics:** +- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections + +**Auto-Discovery:** +- None needed (standard maintenance section) + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tag in first 10 lines +- ✅ File size > 100 lines (reduced from 300+ due to table format + removed domain-specific principles) +- ✅ All 8 core principles present (Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design) + +**MCP Ref Hints:** +- Research: "YAGNI principle examples" (if user wants deeper explanation) +- Research: "DRY principle best practices" (if user wants industry context) + + + +--- + +**Version:** 4.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-112-reference-docs-creator/SKILL.md b/skills/ln-112-reference-docs-creator/SKILL.md new file mode 100644 index 0000000..55675ee --- /dev/null +++ b/skills/ln-112-reference-docs-creator/SKILL.md @@ -0,0 +1,325 @@ +--- +name: ln-112-reference-docs-creator +description: Creates reference documentation structure (docs/reference/ with README, adrs/, guides/, manuals/ directories). Second worker in ln-110-documents-pipeline. +--- + +# Reference Documentation Creator + +This skill creates the reference documentation structure: docs/reference/README.md (hub with registries for ADRs/Guides/Manuals) and empty subdirectories for storing reference materials. + +## When to Use This Skill + +**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator. + +This skill should be used directly when: +- Creating only reference documentation structure (docs/reference/) +- Setting up directories for ADRs, guides, and manuals +- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup) + +## How It Works + +The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation. + +--- + +### Phase 1: Create Structure + +**Objective**: Establish reference documentation directories and README hub. + +**Process**: + +**1.1 Check & create directories**: +- Check if `docs/reference/adrs/` exists → create if missing +- Check if `docs/reference/guides/` exists → create if missing +- Check if `docs/reference/manuals/` exists → create if missing +- Log for each: "✓ Created docs/reference/[name]/" or "✓ docs/reference/[name]/ already exists" + +**1.2 Check & create README**: +- Check if `docs/reference/README.md` exists +- If exists: + - Skip creation + - Log: "✓ docs/reference/README.md already exists, proceeding to validation" +- If NOT exists: + - Copy template: `ln-112-reference-docs-creator/references/reference_readme_template.md` → `docs/reference/README.md` + - Replace placeholders: + - `{{VERSION}}` — "1.0.0" + - `{{DATE}}` — current date (YYYY-MM-DD) + - `{{ADR_LIST}}` — kept as placeholder (filled in Phase 3) + - `{{GUIDE_LIST}}` — kept as placeholder (filled in Phase 3) + - `{{MANUAL_LIST}}` — kept as placeholder (filled in Phase 3) + - Log: "✓ Created docs/reference/README.md from template" + +**1.3 Output**: +``` +docs/reference/ +├── README.md # Created or existing +├── adrs/ # Empty, ready for ADRs +├── guides/ # Empty, ready for guides +└── manuals/ # Empty, ready for manuals +``` + +--- + +### Phase 2: Validate Structure + +**Objective**: Ensure reference/README.md complies with structural requirements and auto-fix violations. + +**Process**: + +**2.1 Check SCOPE tag**: +- Read `docs/reference/README.md` (first 5 lines) +- Check for `` tag +- Expected: `` +- If missing: + - Use Edit tool to add SCOPE tag at line 1 (after first heading) + - Track violation: `scope_tag_added = True` + +**2.2 Check required sections**: +- Load expected sections from `references/questions.md` +- Required sections: + - "Architecture Decision Records (ADRs)" + - "Project Guides" + - "Package Manuals" +- For each section: + - Check if `## [Section Name]` header exists + - If missing: + - Use Edit tool to add section with placeholder: + ```markdown + ## [Section Name] + + {{PLACEHOLDER}} + ``` + - Track violation: `missing_sections += 1` + +**2.3 Check Maintenance section**: +- Search for `## Maintenance` header +- If missing: + - Use Edit tool to add at end of file: + ```markdown + ## Maintenance + + **Last Updated:** [current date] + + **Update Triggers:** + - New ADRs added to adrs/ directory + - New guides added to guides/ directory + - New manuals added to manuals/ directory + + **Verification:** + - [ ] All ADR links in registry are valid + - [ ] All guide links in registry are valid + - [ ] All manual links in registry are valid + - [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files + ``` + - Track violation: `maintenance_added = True` + +**2.4 Check POSIX file endings**: +- Check if file ends with single blank line +- If missing: + - Use Edit tool to add final newline + - Track fix: `posix_fixed = True` + +**2.5 Report validation**: +- Log summary: + ``` + ✅ Structure validation complete: + - SCOPE tag: [added/present] + - Missing sections: [count] sections added + - Maintenance section: [added/present] + - POSIX endings: [fixed/compliant] + ``` +- If violations found: "⚠️ Auto-fixed [total] structural violations" + +--- + +### Phase 3: Validate Content + +**Objective**: Ensure each section answers its questions with meaningful content and populate registries from auto-discovery. + +**Process**: + +**3.1 Load validation spec**: +- Read `references/questions.md` +- Parse questions and validation heuristics for all 3 sections + +**3.2 Validate sections (parametric loop)**: + +Define section parameters: +``` +sections = [ + { + "name": "Architecture Decision Records (ADRs)", + "question": "Where are architecture decisions documented?", + "directory": "docs/reference/adrs/", + "placeholder": "{{ADR_LIST}}", + "glob_pattern": "docs/reference/adrs/*.md", + "heuristics": [ + "Contains link: [ADRs](adrs/) or [adrs](adrs/)", + "Mentions 'Architecture Decision Record' or 'ADR'", + "Has placeholder {{ADR_LIST}} or actual list", + "Length > 30 words" + ] + }, + { + "name": "Project Guides", + "question": "Where are reusable project patterns documented?", + "directory": "docs/reference/guides/", + "placeholder": "{{GUIDE_LIST}}", + "glob_pattern": "docs/reference/guides/*.md", + "heuristics": [ + "Contains link: [Guides](guides/) or [guides](guides/)", + "Has placeholder {{GUIDE_LIST}} or actual list", + "Length > 20 words" + ] + }, + { + "name": "Package Manuals", + "question": "Where are third-party package references documented?", + "directory": "docs/reference/manuals/", + "placeholder": "{{MANUAL_LIST}}", + "glob_pattern": "docs/reference/manuals/*.md", + "heuristics": [ + "Contains link: [Manuals](manuals/) or [manuals](manuals/)", + "Has placeholder {{MANUAL_LIST}} or actual list", + "Length > 20 words" + ] + } +] +``` + +For each section in sections: + +1. **Read section content**: + - Extract section from reference/README.md + +2. **Check if content answers question**: + - Apply validation heuristics + - If ANY heuristic passes → content valid, skip to next section + - If ALL fail → content invalid, continue + +3. **Auto-discovery** (if content invalid or placeholder present): + - Scan directory using Glob tool (section.glob_pattern) + - If files found: + - Extract filenames + - Generate dynamic list: + ```markdown + - [ADR-001: Frontend Framework](adrs/adr-001-frontend-framework.md) + - [02-Repository Pattern](guides/02-repository-pattern.md) + - [Axios 1.6](manuals/axios-1.6.md) + ``` + - Use Edit tool to replace placeholder with generated list + - Track change: `sections_populated += 1` + - If NO files: + - Keep placeholder as-is + - Track: `placeholders_kept += 1` + +4. **Skip external API calls**: + - Do NOT use MCP Ref search (template already has format examples) + +**3.3 Report content validation**: +- Log summary: + ``` + ✅ Content validation complete: + - Sections checked: 3 + - Populated from auto-discovery: [count] + - Placeholders kept (no files): [count] + - Already valid: [count] + ``` + +--- + +## Complete Output Structure + +``` +docs/ +└── reference/ + ├── README.md # Reference hub with registries + ├── adrs/ # Empty or with ADR files + ├── guides/ # Empty or with guide files + └── manuals/ # Empty or with manual files +``` + +--- + +## Reference Files Used + +### Templates + +**Reference README Template**: +- `references/reference_readme_template.md` (v2.0.0) - Reference hub with: + - SCOPE tags (reference documentation ONLY) + - Three registry sections with placeholders + - Maintenance section + +**Validation Specification**: +- `references/questions.md` (v1.0) - Question-driven validation: + - Questions each section must answer + - Validation heuristics + - Auto-discovery hints + +--- + +## Best Practices + +- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks) +- **Parametric validation**: Phase 3 uses loop for 3 sections (no code duplication) +- **Auto-discovery first**: Scan actual files before external API calls +- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation) +- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT + +--- + +## Prerequisites + +**Invoked by**: ln-110-documents-pipeline orchestrator + +**Requires**: +- `docs/` directory (created by ln-111-root-docs-creator) + +**Creates**: +- `docs/reference/` directory structure with README hub +- Validated structure and content (auto-discovery from existing files) + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +**✅ Structure Created:** +- [ ] `docs/reference/` directory exists +- [ ] `docs/reference/adrs/` directory exists +- [ ] `docs/reference/guides/` directory exists +- [ ] `docs/reference/manuals/` directory exists +- [ ] `docs/reference/README.md` exists (created or existing) + +**✅ Structure Validated:** +- [ ] SCOPE tag present in first 5 lines +- [ ] Three registry sections present (ADRs, Guides, Manuals) +- [ ] Maintenance section present at end +- [ ] POSIX file endings compliant + +**✅ Content Validated:** +- [ ] All sections checked against questions.md +- [ ] Placeholders populated from auto-discovery OR kept if no files +- [ ] No validation heuristic failures + +**✅ Reporting:** +- [ ] Phase 1 logged: creation summary +- [ ] Phase 2 logged: structural fixes (if any) +- [ ] Phase 3 logged: content updates (if any) + +--- + +## Technical Details + +**Standards**: +- Michael Nygard's ADR Format (7 sections) +- ISO/IEC/IEEE 29148:2018 (Documentation standards) + +**Language**: English only + +--- + +**Version:** 7.1.0 (MINOR: Workflow optimization - merged Phase 1+2 CREATE, removed redundant Phase 2 Step 3 verification, removed Phase 3.4 project-specific standards check, parametrized Phase 4 content validation. No functionality change, pure refactoring for clarity and efficiency.) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-112-reference-docs-creator/diagram.html b/skills/ln-112-reference-docs-creator/diagram.html new file mode 100644 index 0000000..1505fed --- /dev/null +++ b/skills/ln-112-reference-docs-creator/diagram.html @@ -0,0 +1,98 @@ + + + + + + ln-112-reference-docs-creator - State Diagram + + + + +
+
+

📚 ln-112-reference-docs-creator

+

Reference Documentation Creator - State Diagram

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Create reference documentation structure (adrs/, guides/, manuals/) + README hub
    • +
  • Worker for: ln-110-documents-pipeline orchestrator
    • +
  • Phases: 4 phases (Phase 1+2 CREATE merged → Phase 3 Structure Validation → Phase 4 Content Validation)
    • +
  • Optimization: Merged Phase 1+2 CREATE, removed redundant verifications, parametrized validation
    • +
  • Output: Empty structure with registries ready for content creation
    • +
+
+ +
+
+
+ Creation Action +
+
+
+ Validation +
+
+
+ Success State +
+
+ +
+
+graph TD + Start([Start: Reference Docs Creation]) --> Phase1[Phase 1+2: Create Structure merged
Create dirs + README + ADR template] + + Phase1 --> CreateAll[Create subdirectories adrs/, guides/, manuals/
+ README.md + _template.md] + CreateAll --> ReplaceVars[Replace placeholders:
DATE, registries] + + ReplaceVars --> Phase3[Phase 3: Structure Validation
Verify dirs, SCOPE tags, registries] + Phase3 --> Phase4[Phase 4: Content Validation
Parametric validation with questions.md] + + Phase4 --> Notify[Notify: Reference structure
created + validated] + + Notify --> End([End: ✓ Reference structure ready]) + + %% Styling + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px + classDef success fill:#B3E5FC,stroke:#0277BD,stroke-width:2px + + class Phase1,CreateAll,ReplaceVars action + class Phase3,Phase4 validation + class Notify action + class End success +
+
+ +
+

🔑 Key Features

+
    +
  • Second Worker: Creates reference documentation structure after root docs
    • +
  • Structure Only: Creates directories and registries, NOT content
    • +
  • ADR Template: Copies Michael Nygard's 7-section ADR template
    • +
  • Validation: Parametric content validation (Phase 4) with project-specific standards removal
    • +
+
+ +
+

Generated for ln-112-reference-docs-creator skill | Version 7.1.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-18

+
+
+ + + + diff --git a/skills/ln-112-reference-docs-creator/references/questions.md b/skills/ln-112-reference-docs-creator/references/questions.md new file mode 100644 index 0000000..85e2ae7 --- /dev/null +++ b/skills/ln-112-reference-docs-creator/references/questions.md @@ -0,0 +1,119 @@ +# Reference Documentation Questions + +**Purpose:** Define what each section of reference documentation should answer. + +**Format:** Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints + +--- + +## Table of Contents + +| Document | Questions | Auto-Discovery | Priority | Line | +|----------|-----------|----------------|----------|------| +| [docs/reference/README.md](#docsreferencereadmemd) | 3 | High | High | L23 | + +**Priority Legend:** +- **Critical:** Must answer all questions +- **High:** Strongly recommended +- **Medium:** Optional (can use template defaults) + +**Auto-Discovery Legend:** +- **None:** No auto-discovery needed (use template as-is) +- **Low:** 1-2 questions need auto-discovery +- **High:** All questions need auto-discovery + +--- + + +## docs/reference/README.md + +**File:** docs/reference/README.md (reference documentation hub) +**Target Sections:** Architecture Decision Records (ADRs), Project Guides, Package Manuals + +**Rules for this document:** +- Hub file for reference documentation subdirectories +- Must link to adrs/, guides/, manuals/ directories +- Auto-discovery of existing files in each directory + +--- + + +### Question 1: Where are architecture decisions documented? + +**Expected Answer:** Link to adrs/ directory, ADR format description (Nygard template), list of existing ADRs or placeholder +**Target Section:** ## Architecture Decision Records (ADRs) + +**Validation Heuristics:** +- ✅ Contains link: `[ADRs](adrs/)` or `[adrs](adrs/)` +- ✅ Mentions "Architecture Decision Record" or "ADR" +- ✅ Has placeholder `{{ADR_LIST}}` or actual ADR list +- ✅ Length > 30 words + +**Auto-Discovery:** +- Scan `docs/reference/adrs/` for *.md files +- Generate list dynamically from filenames +- Example: `adr-001-frontend-framework.md` → "ADR-001: Use React+Next.js" + +**MCP Ref Hints:** +- Research: "Michael Nygard ADR format" (if no ADRs exist and need to explain format) +- Extract: ADR template structure (Context, Decision, Status, Consequences) + + +--- + + +### Question 2: Where are reusable project patterns documented? + +**Expected Answer:** Link to guides/ directory, description of guide purpose (reusable patterns, how-tos), list of existing guides or placeholder +**Target Section:** ## Project Guides + +**Validation Heuristics:** +- ✅ Contains link: `[Guides](guides/)` or `[guides](guides/)` +- ✅ Mentions "patterns" or "guides" or "how-to" +- ✅ Has placeholder `{{GUIDE_LIST}}` or actual guide list +- ✅ Length > 20 words + +**Auto-Discovery:** +- Scan `docs/reference/guides/` for *.md files +- Generate list dynamically from filenames +- Example: `authentication-flow.md` → "Authentication Flow Guide" + +**MCP Ref Hints:** +- N/A (guides are project-specific) + + +--- + + +### Question 3: Where are third-party package references documented? + +**Expected Answer:** Link to manuals/ directory, description of manual purpose (package API references, version-specific), list of existing manuals or placeholder +**Target Section:** ## Package Manuals + +**Validation Heuristics:** +- ✅ Contains link: `[Manuals](manuals/)` or `[manuals](manuals/)` +- ✅ Mentions "packages" or "API reference" or "manuals" +- ✅ Has placeholder `{{MANUAL_LIST}}` or actual manual list +- ✅ Length > 20 words + +**Auto-Discovery:** +- Scan `docs/reference/manuals/` for *.md files +- Generate list dynamically from filenames +- Example: `axios-1.6.md` → "Axios 1.6 API Manual" + +**MCP Ref Hints:** +- N/A (manuals are package-specific, created by ln-323-manual-creator) + + +--- + +**Overall File Validation:** +- ✅ Has links to all 3 subdirectories (adrs/, guides/, manuals/) +- ✅ Total length > 60 words + + + +--- + +**Version:** 2.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-112-reference-docs-creator/references/reference_readme_template.md b/skills/ln-112-reference-docs-creator/references/reference_readme_template.md new file mode 100644 index 0000000..b01372e --- /dev/null +++ b/skills/ln-112-reference-docs-creator/references/reference_readme_template.md @@ -0,0 +1,63 @@ +# Reference Documentation + +**Version:** {{VERSION}} +**Last Updated:** {{DATE}} + + + + +--- + +## Overview + +This directory contains reusable knowledge base and architecture decisions: + +- **Architecture Decision Records (ADRs)** - Key technical decisions +- **Project Guides** - Reusable patterns and best practices +- **Package Manuals** - API reference for external libraries + +--- + +## Architecture Decision Records (ADRs) + + + +{{ADR_LIST}} + +--- + +## Project Guides + + + +{{GUIDE_LIST}} + +--- + +## Package Manuals + + + +{{MANUAL_LIST}} + +--- + +## Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New ADRs added to adrs/ directory +- New guides added to guides/ directory +- New manuals added to manuals/ directory + +**Verification:** +- [ ] All ADR links in registry are valid +- [ ] All guide links in registry are valid +- [ ] All manual links in registry are valid +- [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files + +--- + +**Template Version:** 2.0.0 +**Template Last Updated:** {{DATE}} diff --git a/skills/ln-113-tasks-docs-creator/SKILL.md b/skills/ln-113-tasks-docs-creator/SKILL.md new file mode 100644 index 0000000..fd062f1 --- /dev/null +++ b/skills/ln-113-tasks-docs-creator/SKILL.md @@ -0,0 +1,509 @@ +--- +name: ln-113-tasks-docs-creator +description: Creates task management documentation (docs/tasks/README.md + kanban_board.md). Third worker in ln-110-documents-pipeline. Sets up Linear integration and task tracking rules. +--- + +# Tasks Documentation Creator + +This skill creates task management documentation: docs/tasks/README.md (task management system rules) and docs/tasks/kanban_board.md (Linear integration with Epic Story Counters). + +## When to Use This Skill + +**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator OR used standalone. + +Use this skill when: +- Creating task management documentation (docs/tasks/) +- Setting up Linear integration and kanban board +- Validating existing task documentation structure and content +- Configuring Linear team settings (Team Name, UUID, Key) + +**Part of workflow**: ln-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → **ln-113-tasks-docs-creator** → ln-114-project-docs-creator → ln-115-presentation-creator + +## How It Works + +The skill follows a **3-phase workflow**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT. + +**Phase 1: CREATE** - Create tasks/README.md from template with SCOPE tags, workflow rules, Linear integration +**Phase 2: VALIDATE STRUCTURE** - Auto-fix structural violations (SCOPE tags, sections, Maintenance, POSIX) +**Phase 3: VALIDATE CONTENT** - Validate semantic content + special Linear Configuration handling (placeholder detection, UUID/Team Key validation, interactive user prompts) + +--- + +## Phase 1: Create tasks/README.md + +**Objective**: Create task management system documentation from template. + +**When to execute**: Always (first phase) + +**Process**: + +1. **Check if tasks/README.md exists**: + - Use Glob tool: `pattern: "docs/tasks/README.md"` + - If file exists: + - Skip creation + - Log: `✓ docs/tasks/README.md already exists (preserved)` + - Proceed to Phase 2 + - If NOT exists: + - Continue to step 2 + +2. **Create tasks directory**: + - Create the `docs/tasks/` directory if it doesn't exist + +3. **Create tasks/README.md from template**: + - Copy template: `references/tasks_readme_template.md` (v2.0.0) → `docs/tasks/README.md` + - Replace placeholders: + - `{{DATE}}` → current date (YYYY-MM-DD) + - Template contains: + - SCOPE tags: `` + - Story-Level Test Task Pattern + - Kanban Board Structure (Epic Grouping Pattern) + - Linear Integration (MCP methods) + - Maintenance section + +4. **Notify user**: + - If created: `✓ Created docs/tasks/README.md with task management rules` + - If skipped: `✓ docs/tasks/README.md already exists (preserved)` + +**Output**: docs/tasks/README.md (created or existing) + +--- + +## Phase 2: Validate Structure + +**Objective**: Ensure tasks/README.md and kanban_board.md comply with structural requirements. Auto-fix violations. + +**When to execute**: After Phase 1 completes (files exist or created) + +**Process**: + +### 2.1 Validate SCOPE tags + +**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists) + +For each file: +1. Read first 5 lines +2. Check for `` tag +3. Expected values: + - tasks/README.md: `` + - kanban_board.md: `` +4. **If missing:** + - Use Edit tool to add SCOPE tag after first heading + - Log: `⚠ Auto-fixed: Added missing SCOPE tag to {filename}` + +### 2.2 Validate required sections + +**Load validation spec**: +- Read `references/questions.md` +- Extract section names from questions + +**For tasks/README.md**: +- Required sections (from questions.md): + - "Linear Integration" OR "Core Concepts" (Linear MCP methods) + - "Task Workflow" OR "Critical Rules" (state transitions) + - "Task Templates" (template references) +- For each section: + - Check if section header exists (case-insensitive) + - **If missing:** + - Use Edit tool to add section with placeholder content + - Log: `⚠ Auto-fixed: Added missing section '{section}' to tasks/README.md` + +**For kanban_board.md** (if exists): +- Required sections: + - "Linear Configuration" (Team Name, UUID, Key) + - "Work in Progress" OR "Epic Tracking" (Kanban sections) +- For each section: + - Check if section header exists + - **If missing:** + - Use Edit tool to add section with placeholder + - Log: `⚠ Auto-fixed: Added missing section '{section}' to kanban_board.md` + +### 2.3 Validate Maintenance section + +**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists) + +For each file: +1. Search for `## Maintenance` header in last 20 lines +2. **If missing:** + - Use Edit tool to add at end of file: + ```markdown + ## Maintenance + + **Update Triggers:** + - When Linear workflow changes + - When task templates are added/modified + - When label taxonomy changes + + **Last Updated:** {current_date} + ``` + - Log: `⚠ Auto-fixed: Added Maintenance section to {filename}` + +### 2.4 Validate POSIX line endings + +**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists) + +For each file: +1. Check if file ends with single newline character +2. **If missing:** + - Use Edit tool to add final newline + - Log: `⚠ Auto-fixed: Added POSIX newline to {filename}` + +### 2.5 Report validation summary + +Log summary: +``` +✓ Structure validation completed: + tasks/README.md: + - SCOPE tag: [added/present] + - Required sections: [count] sections [added/present] + - Maintenance section: [added/present] + - POSIX endings: [fixed/compliant] + kanban_board.md: + - SCOPE tag: [added/present/skipped - file not exists] + - Required sections: [count] sections [added/present/skipped] + - Maintenance section: [added/present/skipped] + - POSIX endings: [fixed/compliant/skipped] +``` + +If violations found: `⚠ Auto-fixed {total} structural violations` + +**Output**: Structurally valid task management documentation + +--- + +## Phase 3: Validate Content + +**Objective**: Ensure each section answers its validation questions with meaningful content. Special handling for Linear Configuration (placeholder detection, user prompts, UUID/Team Key validation). + +**When to execute**: After Phase 2 completes (structure valid, auto-fixes applied) + +**Process**: + +### 3.1 Load validation spec + +1. Read `references/questions.md` +2. Parse document sections and questions +3. Extract validation heuristics for each section + +### 3.2 Validate kanban_board.md → Linear Configuration (Special Handling) + +**Question**: "What is the Linear team configuration?" + +**Step 3.2.1: Check if kanban_board.md exists**: +- Use Glob tool: `pattern: "docs/tasks/kanban_board.md"` +- If NOT exists: + - Log: `ℹ kanban_board.md not found - skipping Linear Configuration validation` + - Skip to Step 3.3 +- If exists: + - Continue to Step 3.2.2 + +**Step 3.2.2: Read Linear Configuration section**: +- Read `docs/tasks/kanban_board.md` +- Locate `## Linear Configuration` section +- Extract Team Name, Team UUID, Team Key values + +**Step 3.2.3: Placeholder Detection**: + +Check for placeholders: +``` +Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY] +If ANY placeholder present → Interactive Setup Mode +If NO placeholders present → Validation Mode +``` + +**Interactive Setup Mode** (if placeholders detected): + +1. **Prompt user for Team Name**: + - Question: "What is your Linear Team Name?" + - Validation: Non-empty string + - Example: "My Project Team" + +2. **Prompt user for Team UUID**: + - Question: "What is your Linear Team UUID?" + - Format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` + - Validation Regex: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/` + - **If invalid:** + - Show error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)" + - Re-prompt user + - Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + +3. **Prompt user for Team Key**: + - Question: "What is your Linear Team Key (2-4 uppercase letters)?" + - Format: 2-4 uppercase letters + - Validation Regex: `/^[A-Z]{2,4}$/` + - **If invalid:** + - Show error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)" + - Re-prompt user + - Example: "PROJ" + +4. **Replace placeholders**: + - Use Edit tool to replace in kanban_board.md: + - `[TEAM_NAME]` → `{user_team_name}` + - `[TEAM_UUID]` → `{user_team_uuid}` + - `[TEAM_KEY]` → `{user_team_key}` + - `[WORKSPACE_URL]` → `https://linear.app/{workspace_slug}` (if placeholder exists) + +5. **Set initial counters** (if table exists): + - Set "Next Epic Number" → 1 + - Set "Next Story Number" → 1 + +6. **Update Last Updated date**: + - Replace `[YYYY-MM-DD]` → `{current_date}` in Maintenance section + +7. **Save updated kanban_board.md** + +8. **Log success**: + ``` + ✓ Linear configuration updated: + - Team Name: {user_team_name} + - Team UUID: {user_team_uuid} + - Team Key: {user_team_key} + - Next Epic Number: 1 + - Next Story Number: 1 + ``` + +**Validation Mode** (if real values present, no placeholders): + +1. **Extract existing values**: + - Extract Team UUID from line matching: `Team UUID: {value}` or in table + - Extract Team Key from line matching: `Team Key: {value}` or in table + +2. **Validate formats**: + - UUID: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/` + - Team Key: `/^[A-Z]{2,4}$/` + +3. **If validation fails**: + ``` + ⚠ Invalid format detected in Linear Configuration: + - Team UUID: {uuid} (expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) + - Team Key: {key} (expected: 2-4 uppercase letters) + + Fix manually or re-run skill to replace with correct values. + ``` + - Mark as invalid but continue (don't block) + +4. **If validation passes**: + ``` + ✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key}) + ``` + +### 3.3 Validate tasks/README.md sections + +**Parametric loop for 3 questions** (from questions.md): + +For each question in: +1. "How is Linear integrated into the task management system?" +2. "What are the task state transitions and review criteria?" +3. "What task templates are available and how to use them?" + +**Validation process**: +1. Extract validation heuristics from questions.md +2. Read corresponding section content from tasks/README.md +3. Check if **ANY** heuristic passes: + - Contains keyword X → pass + - Has pattern Y → pass + - Length > N words → pass +4. If ANY passes → Section valid +5. If NONE passes → Log warning: `⚠ Section may be incomplete: {section_name}` + +**Example validation (Question 1: Linear Integration)**: +``` +Heuristics: +- Contains "Linear" or "MCP" → pass +- Mentions team ID or UUID → pass +- Has workflow states (Backlog, Todo, In Progress) → pass +- Length > 100 words → pass + +Check content: +- ✓ Contains "Linear" → PASS +→ Section valid +``` + +**No auto-discovery needed** (workflow is standardized in template) + +### 3.4 Validate kanban_board.md → Epic Tracking + +**Question**: "Are Epics being tracked in the board?" + +**If kanban_board.md exists**: + +**Validation heuristics**: +``` +- Has "Epic" or "Epics Overview" section header → pass +- Has table with columns: Epic, Name, Status, Progress → pass +- OR has placeholder: "No active epics" → pass +- Length > 20 words → pass +``` + +**Action**: +1. Read Epic Tracking or Epics Overview section +2. Check if ANY heuristic passes +3. If passes → valid +4. If none pass → log warning: `⚠ Epic Tracking section may be incomplete` + +**If kanban_board.md does NOT exist**: +- Skip validation +- Log: `ℹ Epic Tracking validation skipped (kanban_board.md not found)` + +### 3.5 Report content validation summary + +Log summary: +``` +✓ Content validation completed: + tasks/README.md: + - ✓ Linear Integration: valid (contains "Linear", "MCP", workflow states) + - ✓ Task Workflow: valid (contains state transitions) + - ✓ Task Templates: valid (contains template references) + kanban_board.md: + - ✓ Linear Configuration: {status} (Team: {name}, UUID: {uuid}, Key: {key}) + - ✓ Epic Tracking: valid (table present or placeholder) +``` + +**Output**: Validated and potentially updated task management documentation with Linear configuration + +--- + +## Complete Output Structure + +``` +docs/ +└── tasks/ + ├── README.md # Task management system rules + └── kanban_board.md # Linear integration (optional, created manually or by other skills) +``` + +**Note**: Kanban board updated by ln-311-task-creator, ln-312-task-replanner, ln-330-story-executor (Epic Grouping logic). + +--- + +## Reference Files Used + +### Templates + +**Tasks README Template**: +- `references/tasks_readme_template.md` (v2.0.0) - Task management system rules with: + - SCOPE tags (task management ONLY) + - Story-Level Test Task Pattern (tests in final Story task, NOT scattered) + - Kanban Board Structure (Epic Grouping Pattern with Status → Epic → Story → Tasks hierarchy) + - Linear Integration (MCP methods: create_project, create_issue, update_issue, list_issues) + - Maintenance section (Update Triggers, Verification, Last Updated) + +**Kanban Board Template**: +- `references/kanban_board_template.md` (v3.0.0) - Linear integration template with: + - Linear Configuration table (Team Name, UUID, Key, Workspace URL) + - Epic Story Counters table (Next Epic Number, Story counters per Epic) + - Kanban sections: Backlog, Todo (✅ APPROVED), In Progress, To Review, To Rework, Done (Last 5 tasks), Postponed + - Epic Grouping Pattern format (Epic header → 📖 Story → Task with indentation) + - Placeholders for Epic/Story/Task entries + +### Validation Specification + +**questions.md**: +- `references/questions.md` (v1.0) - Validation questions for task management documentation: + - 5 sections (3 for tasks/README.md, 2 for kanban_board.md) + - Question format: Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints + - Special handling section for Linear Configuration (placeholder detection, UUID/Team Key validation) + +--- + +## Best Practices + +- **Story-Level Test Task Pattern**: Tests consolidated in final Story task, NOT scattered across implementation tasks +- **Epic Grouping Pattern**: Epic context always visible, 0/2/4 space indentation (Epic → Story → Tasks) +- **Linear MCP**: All task operations use Linear MCP methods (create_project, create_issue, update_issue) +- **SCOPE Tags**: Include in first 3-5 lines of all documentation files +- **Idempotent**: Can be invoked multiple times - checks file existence, preserves existing files, re-validates on each run + +--- + +## Prerequisites + +**Orchestrator**: ln-110-documents-pipeline (invokes this worker in Phase 3, Step 3.3) + +**Standalone usage**: Can also be invoked directly for: +- Creating only task management documentation +- Re-validating existing task documentation +- Setting up Linear Configuration interactively + +**Idempotent**: Yes - can be invoked multiple times without side effects. The skill: +- Checks file existence before creation (preserves existing files) +- Re-validates structure and content on each run +- Auto-fixes structural violations (SCOPE tags, sections, Maintenance, POSIX) +- Updates Linear Configuration if placeholders detected + +**Dependencies**: None (standalone worker) + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +### Phase 1: CREATE + +**✅ tasks/README.md:** +- [ ] `docs/tasks/` directory created (if didn't exist) +- [ ] `docs/tasks/README.md` created from template (if didn't exist) OR preserved (if existed) +- [ ] All `{{DATE}}` placeholders replaced with current date +- [ ] Template contains SCOPE tags, Story-Level Test Task Pattern, Kanban Board Structure, Linear Integration, Maintenance section +- [ ] User notified: created OR preserved + +### Phase 2: VALIDATE STRUCTURE + +**✅ tasks/README.md:** +- [ ] SCOPE tag present in first 5 lines OR auto-fixed +- [ ] Required sections present (Linear Integration/Core Concepts, Task Workflow/Critical Rules, Task Templates) OR auto-fixed +- [ ] Maintenance section present at end OR auto-fixed +- [ ] POSIX line ending present OR auto-fixed +- [ ] Validation summary logged + +**✅ kanban_board.md (if exists):** +- [ ] SCOPE tag present OR auto-fixed +- [ ] Required sections present (Linear Configuration, Work in Progress/Epic Tracking) OR auto-fixed +- [ ] Maintenance section present OR auto-fixed +- [ ] POSIX line ending present OR auto-fixed +- [ ] Validation summary logged + +### Phase 3: VALIDATE CONTENT + +**✅ tasks/README.md:** +- [ ] Linear Integration section validated (contains "Linear" OR "MCP" OR team ID OR workflow states OR length > 100 words) +- [ ] Task Workflow section validated (contains workflow states OR review criteria OR length > 60 words) +- [ ] Task Templates section validated (contains "template" OR Epic/Story/Task OR links OR length > 40 words) +- [ ] Validation summary logged + +**✅ kanban_board.md (if exists):** +- [ ] Linear Configuration section validated: + - [ ] If placeholders detected ([TEAM_NAME], [TEAM_UUID], [TEAM_KEY]): + - [ ] User prompted for Team Name (non-empty validation) + - [ ] User prompted for Team UUID (regex validation: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/`) + - [ ] User prompted for Team Key (regex validation: `/^[A-Z]{2,4}$/`) + - [ ] Placeholders replaced with user input + - [ ] Next Epic Number set to 1 + - [ ] Next Story Number set to 1 + - [ ] Last Updated date updated + - [ ] If real values present: + - [ ] Team UUID format validated + - [ ] Team Key format validated + - [ ] Validation result logged (valid OR invalid with warning) +- [ ] Epic Tracking section validated (has "Epic" header OR table OR placeholder OR length > 20 words) +- [ ] Validation summary logged + +**✅ Overall:** +- [ ] Summary message displayed: "✓ Task management documentation validated (3-phase complete)" +- [ ] User informed about any auto-fixes applied +- [ ] User informed about Linear Configuration status (if applicable) + +**Output:** docs/tasks/README.md + optionally kanban_board.md (validated, auto-fixed where needed, Linear Configuration set up if placeholders found) + +--- + +## Technical Details + +**Standards**: Story-Level Test Task Pattern, Epic Grouping Pattern (Status → Epic → Story → Tasks), Linear MCP integration + +**Language**: English only + +--- + +**Version:** 7.0.0 (MAJOR: Added Phase 2/3 validation. Merged CREATE+VALIDATE into unified worker. Special Linear Configuration handling with UUID/Team Key validation, user prompts for placeholders. Idempotent.) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-113-tasks-docs-creator/diagram.html b/skills/ln-113-tasks-docs-creator/diagram.html new file mode 100644 index 0000000..01332a6 --- /dev/null +++ b/skills/ln-113-tasks-docs-creator/diagram.html @@ -0,0 +1,123 @@ + + + + + + ln-113-tasks-docs-creator - State Diagram + + + + +
+
+

📋 ln-113-tasks-docs-creator

+

Tasks Documentation Creator - State Diagram

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Create task management documentation (docs/tasks/README.md + kanban_board.md)
    • +
  • Worker for: ln-110-documents-pipeline orchestrator
    • +
  • Phases: 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Content Validation)
    • +
  • Linear Integration: Special handling for Linear Configuration (UUID/Team Key validation, placeholder detection)
    • +
  • Auto-Discovery: Epic Story Counters for automatic team configuration
    • +
+
+ +
+
+
+ Creation Action +
+
+
+ Validation +
+
+
+ Conditional Check +
+
+ +
+
+graph TD + Start([Start: Tasks Docs Creation]) --> Phase1[Phase 1: CREATE tasks/README.md] + + Phase1 --> CheckExists{README.md
exists?} + CheckExists -->|Yes| Preserved[Preserve existing
README.md] + CheckExists -->|No| CreateReadme[Create from template
+ replace DATE placeholder] + + Preserved --> Phase2 + CreateReadme --> Phase2 + + Phase2[Phase 2: Structure Validation
Auto-fix SCOPE tags, sections, Maintenance] + + Phase2 --> AutoFix[Auto-fix violations:
SCOPE tags, required sections,
Maintenance, POSIX endings] + + AutoFix --> Phase3[Phase 3: Content Validation
Semantic validation + Linear Configuration] + + Phase3 --> ValidateReadme[Validate tasks/README.md sections:
Linear Integration, Task Workflow, Templates] + + Phase3 --> CheckKanban{kanban_board.md
exists?} + CheckKanban -->|No| Summary + CheckKanban -->|Yes| LinearConfig[Linear Configuration
Special Handling] + + LinearConfig --> PlaceholderCheck{Has placeholders
[TEAM_NAME/UUID/KEY]?} + + PlaceholderCheck -->|Yes| InteractiveSetup[Interactive Setup Mode
User prompts + validation:
UUID regex, Team Key regex] + PlaceholderCheck -->|No| ValidationMode[Validation Mode
Check UUID/Team Key formats] + + InteractiveSetup --> UpdateConfig[Replace placeholders
+ Set Epic/Story counters to 1] + ValidationMode --> EpicTracking + + UpdateConfig --> EpicTracking[Validate Epic Tracking section] + EpicTracking --> Summary + + ValidateReadme --> Summary[Notify: Task documentation
validated (3-phase complete)] + + Summary --> End([End: ✓ Tasks docs created + validated]) + + %% Styling + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px + classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px + + class Phase1,CreateReadme,Preserved,AutoFix,InteractiveSetup,UpdateConfig,Summary action + class Phase2,Phase3,ValidateReadme,LinearConfig,ValidationMode,EpicTracking validation + class CheckExists,CheckKanban,PlaceholderCheck decision +
+
+ +
+

🔑 Key Features

+
    +
  • Third Worker: Creates task management system after reference docs (ln-110 → ln-111 → ln-112 → ln-113)
    • +
  • Story-Level Test Task Pattern: Documents test consolidation approach (tests in final Story task)
    • +
  • Epic Grouping Pattern: Status → Epic → Story → Tasks hierarchy (0/2/4 space indentation)
    • +
  • Linear Configuration: UUID/Team Key validation with regex, Interactive Setup Mode for placeholders
    • +
  • Epic Story Counters: Auto-discovery integration (Next Epic Number, Story counters per Epic)
    • +
  • Idempotent: Can be invoked multiple times - preserves existing files, re-validates on each run
    • +
+
+ +
+

Generated for ln-113-tasks-docs-creator skill | Version 7.0.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-18

+
+
+ + + + diff --git a/skills/ln-113-tasks-docs-creator/references/kanban_board_template.md b/skills/ln-113-tasks-docs-creator/references/kanban_board_template.md new file mode 100644 index 0000000..4aeaa0d --- /dev/null +++ b/skills/ln-113-tasks-docs-creator/references/kanban_board_template.md @@ -0,0 +1,170 @@ +# Task Navigation + +> **SCOPE:** Quick navigation to active tasks in Linear. Contains ONLY links and titles per Context Budget Rule. DO NOT add: task descriptions, implementation notes, or workflow rules (→ tasks/README.md). + +> **Last Updated**: [YYYY-MM-DD] (Hierarchical format: Status → Epic → Story → Tasks) + +--- + +## Linear Configuration (use MCP Linear) + +**What is Linear:** Issue tracking and project management tool with workspace → initiative → project → issue hierarchy. + +**Our Configuration:** +- **Workspace**: [TEAM_NAME] ([WORKSPACE_URL]) +- **Team**: [TEAM_NAME] (Team Key: [TEAM_KEY]) +- **Initiative**: [Your Initiative Name] +- **Projects**: Each Epic = separate Linear Project +- **Issues**: User Stories (label:user-story, parentId=null) + Tasks (parentId=StoryId) + +**Key Features:** +- Custom views replicate kanban workflow (Backlog → Active → Review → Done) +- Labels for technical categorization (db, api, service, testing) +- Issue titles preserve Epic context (EP{N}_{XX}: Task Name) +- Single source of truth for all task tracking + +**Detailed Guide:** See [docs/guides/25-linear-task-management.md](../guides/25-linear-task-management.md) for: +- Hierarchical structure and best practices +- Custom views, labels, and workflow patterns +- Team keyboard shortcuts and bulk actions + +**Single Source of Truth for all Linear variables** + +| Variable | Value | Description | +|----------|-------|-------------| +| **Team ID** | [TEAM_NAME] | Linear team name | +| **Team UUID** | [TEAM_UUID] | Team UUID for API calls | +| **Team Key** | [TEAM_KEY] | Short key for issues ([TEAM_KEY]-XX) | +| **Workspace URL** | [WORKSPACE_URL] | Linear workspace | +| **Next Epic Number** | 1 | Next available Epic number | + +## Quick Access + +**Views:** +- [Backlog]([WORKSPACE_URL]/team/[TEAM_KEY]/backlog) +- [Todo]([WORKSPACE_URL]/team/[TEAM_KEY]) +- [Active Sprint]([WORKSPACE_URL]/team/[TEAM_KEY]/active) +- [All Issues]([WORKSPACE_URL]/team/[TEAM_KEY]/all) + +--- + +### Epic Story Counters + +| Epic | Last Story | Next Story | Last Task | Next Task | +|------|------------|------------|-----------|-----------| +| Epic 0 | - | US001 | - | EP0_01 | +| Epic 1+ | - | US001 | - | EP1_01 | + +> [!NOTE] + +> User Story numbering starts at US001 for each new Epic. Task numbering starts at EP{N}_01 where N is the Epic number. [TEAM_KEY]-XX numbers are auto-generated by Linear. + +--- + +## Work in Progress + +**Format:** Each status section groups tasks by Epic → Story → Tasks hierarchy. Epic headers (`**Epic N: Title**`) have no indent. Stories have 2-space indent. Tasks have 4-space indent (2 base + 2 for dash). + +**Important:** Stories without tasks are ONLY allowed in Backlog/Postponed statuses with note: `_(tasks not created yet)_` + +### Backlog + +**Epic 0: Common Tasks** + + 📖 [[TEAM_KEY]-XX: US001 Example Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + _( tasks not created yet)_ + +**Epic 1: Example Feature Area** + + 📖 [[TEAM_KEY]-XX: US001 Another Example Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + - [[TEAM_KEY]-XX: EP1_01 Example Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +### Todo + +**Epic 1: Example Feature Area** + + 📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED + - [[TEAM_KEY]-XX: EP1_02 Ready Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + - [[TEAM_KEY]-XX: EP1_03 Another Ready Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +### In Progress + +**Epic 1: Example Feature Area** + + 📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED + - [[TEAM_KEY]-XX: EP1_02 Active Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +### To Review + +**Epic 1: Example Feature Area** + + 📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED + - [[TEAM_KEY]-XX: EP1_02 Task Under Review](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +### To Rework + +**Epic 1: Example Feature Area** + + 📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED + - [[TEAM_KEY]-XX: EP1_02 Task Needing Fixes](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +### Done (Last 5 tasks) + +**Epic 0: Common Tasks** + + 📖 [[TEAM_KEY]-XX: US001 Completed Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ DONE + - [[TEAM_KEY]-XX: EP0_01 Completed Task 1](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + - [[TEAM_KEY]-XX: EP0_02 Completed Task 2](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +**Epic 1: Example Feature Area** + + 📖 [[TEAM_KEY]-XX: US002 Another Completed Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ DONE + - [[TEAM_KEY]-XX: EP1_01 Completed Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +### Postponed + +**Epic 0: Common Tasks** + + 📖 [[TEAM_KEY]-XX: US003 Deferred Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + _(tasks not created yet)_ + +**Epic 2: Future Feature** + + 📖 [[TEAM_KEY]-XX: US001 Postponed Work](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + - [[TEAM_KEY]-XX: EP2_01 Postponed Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) + +--- + +## Epics Overview + +**Active:** +_No active epics yet_ + +**Completed:** +_No completed epics yet_ + +--- + +## Workflow Reference + +| Status | Purpose | +|--------|---------| +| **Backlog** | New tasks requiring estimation and approval | +| **Postponed** | Deferred tasks for future iterations | +| **Todo** | Approved tasks ready for development | +| **In Progress** | Active development | +| **To Review** | Awaiting code review | +| **To Rework** | Needs fixes, returns to In Progress | +| **Done** | Completed and approved | + +**Manual Statuses:** Canceled, Duplicate + +--- + +## Related Documentation +- [tasks/README.md](./README.md) - Task system workflow and rules + +--- + +**Template Version:** 3.0.0 (Epic grouping in ALL Work in Progress sections with examples) +**Last Updated:** 2025-11-15 diff --git a/skills/ln-113-tasks-docs-creator/references/questions.md b/skills/ln-113-tasks-docs-creator/references/questions.md new file mode 100644 index 0000000..e9b100d --- /dev/null +++ b/skills/ln-113-tasks-docs-creator/references/questions.md @@ -0,0 +1,274 @@ +# Task Management Documentation Questions + +**Purpose:** Define validation questions for task management system (tasks/README.md, kanban_board.md). Used in CREATE mode (user answers questions) and VALIDATE mode (check document compliance). + +**Format:** Document → Questions (with target sections) → Validation Heuristics → Auto-Discovery → Special Handling + +--- + +## Table of Contents + +| Document | Questions | Auto-Discovery | Priority | Line | +|----------|-----------|----------------|----------|------| +| [tasks/README.md](#tasksreadmemd) | 3 | None | High | L35 | +| [kanban_board.md](#kanban_boardmd) | 2 | Placeholder Detection | Critical | L110 | + +**Priority Legend:** +- **Critical:** Must answer all questions (Linear Configuration required for workflow) +- **High:** Strongly recommended (standard workflow content) + +**Auto-Discovery Legend:** +- **None:** No auto-discovery needed (workflow is standardized) +- **Placeholder Detection:** Detect and replace placeholders with user input + +--- + + +## tasks/README.md + +**File:** docs/tasks/README.md +**Target Sections:** Linear Integration, Task Workflow, Task Templates + +**Rules for this document:** +- Must have SCOPE tag in first 10 lines +- Must explain Linear MCP integration +- Must document state transitions and review criteria +- Must list available task templates + +--- + + +### Question 1: How is Linear integrated into the task management system? + +**Expected Answer:** Team ID location, issue statuses (Backlog, Todo, In Progress, To Review, Done), label conventions, Linear MCP methods reference, workflow configuration + +**Target Section:** ## Core Concepts, ## Critical Rules, ## Linear MCP Methods Reference + +**Validation Heuristics:** +- ✅ Contains "Linear" or "MCP" → pass +- ✅ Mentions team ID or team UUID → pass +- ✅ Has workflow states: Backlog, Todo, In Progress, To Review, Done → pass +- ✅ Has "Linear MCP Methods" section with examples → pass +- ✅ Length > 100 words → pass + +**Auto-Discovery:** +- None needed (standardized workflow provided by template) + +**MCP Ref Hints:** +- Research "Linear API MCP integration" +- Search "Linear issue workflow states" + + +--- + + +### Question 2: What are the task state transitions and review criteria? + +**Expected Answer:** State transition rules (Backlog → Todo → In Progress → To Review → Done), review criteria, rework process, Epic Grouping Pattern + +**Target Section:** ## Task Workflow, ## Core Concepts + +**Validation Heuristics:** +- ✅ Contains "Backlog" or "Todo" or "In Progress" → pass +- ✅ Mentions "Review" or "To Review" → pass +- ✅ Mentions "Done" or "Completed" → pass +- ✅ Has workflow states diagram or table → pass +- ✅ Mentions "Epic Grouping" → pass +- ✅ Length > 60 words → pass + +**Auto-Discovery:** +- None needed (standard workflow states) + +**MCP Ref Hints:** +- None needed + + +--- + + +### Question 3: What task templates are available and how to use them? + +**Expected Answer:** List of templates (Epic, Story, Task, Test Task), usage guidelines, required sections, links to template files + +**Target Section:** ## Task Workflow, ## Critical Rules + +**Validation Heuristics:** +- ✅ Contains "template" (case insensitive) → pass +- ✅ Mentions "Epic" or "Story" or "Task" → pass +- ✅ Has links to template files or references → pass +- ✅ Mentions "Story-Level Test Strategy" or testing → pass +- ✅ Length > 40 words → pass + +**Auto-Discovery:** +- None needed (templates provided by other skills) + +**MCP Ref Hints:** +- None needed + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tag in first 10 lines: `` +- ✅ Total length > 200 words (meaningful content) +- ✅ Has Maintenance section at end + + + +--- + + +## kanban_board.md + +**File:** docs/tasks/kanban_board.md +**Target Sections:** Linear Configuration, Work in Progress (Epic Tracking) + +**Rules for this document:** +- Must have SCOPE tag in first 10 lines +- Must have Linear Configuration section with Team Name, Team UUID, Team Key +- Must have Epic tracking table or placeholder +- Single Source of Truth for Next Epic/Story Numbers + +--- + + +### Question 1: What is the Linear team configuration? + +**Expected Answer:** Team Name, Team UUID (valid format), Team Key (2-4 uppercase letters), Workspace URL, Next Epic Number (≥1), Next Story Number (≥1) + +**Target Section:** ## Linear Configuration, ## Epic Story Counters + +**Validation Heuristics:** +- ✅ Has Team Name (not placeholder `[TEAM_NAME]`) → pass +- ✅ Has valid UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) → pass +- ✅ Has Team Key (2-4 uppercase letters, e.g., PROJ, WEB, API) → pass +- ✅ Has Next Epic Number (integer ≥ 1) → pass +- ✅ Has Next Story Number (integer ≥ 1) → pass +- ✅ Has Workspace URL or Team ID → pass + +**Auto-Discovery:** +- **Placeholder Detection Pattern:** + - Check for: `[TEAM_NAME]`, `[TEAM_UUID]`, `[TEAM_KEY]` + - If placeholders found → Trigger interactive user prompt (see Special Handling) + - If real values present → Validate format only + +**Special Handling (Phase 3 VALIDATE CONTENT):** + +**Placeholder Detection:** +``` +Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY] +If ANY placeholder present → Interactive Setup Mode +If NO placeholders → Validation Mode +``` + +**Interactive Setup Mode (if placeholders detected):** + +1. **Prompt user for Team Name:** + - Question: "What is your Linear Team Name?" + - Validation: Non-empty string + - Example: "My Project Team" + +2. **Prompt user for Team UUID:** + - Question: "What is your Linear Team UUID?" + - Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + - Validation Regex: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/` + - If invalid → Re-prompt with error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)" + - Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + +3. **Prompt user for Team Key:** + - Question: "What is your Linear Team Key (2-4 uppercase letters)?" + - Format: 2-4 uppercase letters + - Validation Regex: `/^[A-Z]{2,4}$/` + - If invalid → Re-prompt with error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)" + - Example: "PROJ" + +4. **Replace placeholders:** + - Replace `[TEAM_NAME]` → `{user_team_name}` + - Replace `[TEAM_UUID]` → `{user_team_uuid}` + - Replace `[TEAM_KEY]` → `{user_team_key}` + - Replace `[WORKSPACE_URL]` → `https://linear.app/{workspace_slug}` (if placeholder exists) + +5. **Set initial counters:** + - Set "Next Epic Number" → 1 + - Set "Next Story Number" → 1 + +6. **Update Last Updated date:** + - Replace `[YYYY-MM-DD]` → `{current_date}` + +7. **Save updated kanban_board.md** + +8. **Log success:** + ``` + ✓ Linear configuration updated: + - Team Name: {user_team_name} + - Team UUID: {user_team_uuid} + - Team Key: {user_team_key} + - Next Epic Number: 1 + - Next Story Number: 1 + ``` + +**Validation Mode (if real values present):** + +1. **Extract existing values:** + - Extract Team UUID from line matching: `Team UUID: {value}` + - Extract Team Key from line matching: `Team Key: {value}` + +2. **Validate formats:** + - UUID: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/` + - Team Key: `/^[A-Z]{2,4}$/` + +3. **If validation fails:** + ``` + ⚠ Invalid format detected in Linear Configuration: + - Team UUID: {uuid} (expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) + - Team Key: {key} (expected: 2-4 uppercase letters) + + Fix manually or re-run skill to replace with correct values. + ``` + +4. **If validation passes:** + ``` + ✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key}) + ``` + +**MCP Ref Hints:** +- Research "Linear team UUID format" +- Search "Linear workspace configuration" + + +--- + + +### Question 2: Are Epics being tracked in the board? + +**Expected Answer:** Table with Epic data (Epic ID, Name, Status, Progress) or placeholder ("No active epics") + +**Target Section:** ## Work in Progress (Epics Overview subsection) + +**Validation Heuristics:** +- ✅ Has "Epic" or "Epics Overview" section header → pass +- ✅ Has table with columns: Epic, Name, Status, Progress (or similar) → pass +- ✅ OR has placeholder: "No active epics" or "No epics yet" → pass +- ✅ Length > 20 words → pass + +**Auto-Discovery:** +- None needed (Epics are populated by workflow skills: ln-210, ln-220, ln-300) + +**MCP Ref Hints:** +- None needed + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tag in first 10 lines: `` +- ✅ Has Linear Configuration section with valid Team Name, UUID, Key +- ✅ Has Epic Story Counters table +- ✅ Has Maintenance section at end + + + +--- + +**Version:** 1.0 +**Last Updated:** 2025-11-18 diff --git a/skills/ln-113-tasks-docs-creator/references/tasks_readme_template.md b/skills/ln-113-tasks-docs-creator/references/tasks_readme_template.md new file mode 100644 index 0000000..fa70a07 --- /dev/null +++ b/skills/ln-113-tasks-docs-creator/references/tasks_readme_template.md @@ -0,0 +1,541 @@ +# Task Tracking System + +> **SCOPE:** Task tracking system workflow and rules ONLY. Contains task lifecycle, naming conventions, and integration rules. DO NOT add: actual task details (→ task files), kanban status (→ kanban_board.md), or implementation guides (→ guides/). + +--- + +## Overview + +This folder contains the project's task management system, organizing all development work into trackable units with clear status progression. + +### Folder Structure + +``` +docs/tasks/ +├── README.md # This file - Task tracking workflow and rules +└── kanban_board.md # Live navigation to active tasks in Linear +``` + +> [!NOTE] + +> All task tracking (Epics, User Stories, tasks) is handled in Linear. Linear is the single source of truth. + +**Live Navigation**: [Kanban Board](kanban_board.md) + +--- + +## Core Concepts + +### Task Lifecycle + +**Workflow:** +``` +Backlog/Postponed → Todo → In Progress → To Review → Done + ↓ + To Rework → (back to In Progress) +``` + +**Statuses:** +- **Backlog:** New tasks requiring estimation and approval +- **Postponed:** Deferred tasks for future iterations +- **Todo:** Approved tasks ready for development +- **In Progress:** Currently being developed +- **To Review:** Awaiting code review and validation +- **To Rework:** Needs fixes after review +- **Done:** Completed, reviewed, tested, approved + +**Manual Statuses** (not in workflow): Canceled, Duplicate + +### Epic Structure + +**Organization in Linear:** +- **Epic** = Linear Project (contains all User Stories and tasks for epic) +- **User Story** = Linear Issue with `label: user-story` and `parentId: null` +- **Task** = Linear Issue with `parentId: ` + +**Epic Fields:** Name, description, start date, target date, project lead +**User Story Format:** "As a... I want... So that..." + Given-When-Then acceptance criteria +**Task Format:** Context, requirements, acceptance criteria, implementation notes + +### Foundation-First Execution Order + +**Critical Rule**: Foundation tasks are executed BEFORE consumer tasks (for testability). + +**Definitions**: +- **Foundation** = Database, Repository, core services +- **Consumer** = API endpoints, Frontend components that USE foundation + +**Rationale**: Each layer is testable when built (can't test API without working DB). + +**Example**: +``` +✅ CORRECT EXECUTION ORDER: + Task 1: Database schema + Repository (foundation) + Task 2: Service layer with business logic + Task 3: API endpoint (consumer) + Task 4: Frontend dashboard (consumer) + +❌ WRONG (can't test): + Task 1: Frontend dashboard calls /api/users + Task 2: API endpoint (no DB to test against) +``` + +> **Note:** Consumer-First is for API/interface DESIGN (think from consumer perspective), Foundation-First is for EXECUTION ORDER (build testable foundation first). + +--- + +## Critical Rules + +### Rule 1: Linear Integration (MCP Methods ONLY) + +**CRITICAL**: Use ONLY `mcp__linear-server__*` methods for all Linear operations. + +**PROHIBITED**: +- `gh` command (GitHub CLI) +- GitHub API calls +- Direct Linear API calls +- Manual task creation in Linear UI (for automated workflows) + +**Rationale**: +- MCP Linear provides type-safe, validated operations +- Prevents data inconsistencies +- Ensures proper error handling + +**See**: [Linear MCP Methods Reference](#linear-mcp-methods-reference) below + +--- + +### Rule 2: Integration Rules + +#### Tests + +**Rule**: Tests are created ONLY in the final Story task (Story Finalizer test task). + +**NEVER** create: +- Separate test tasks during implementation +- Tests in implementation tasks (implementation tasks focus on feature code only) + +**Process**: +1. Implementation tasks (1-6 tasks) → To Review → Done +2. ln-340-story-quality-gate Pass 1 → Manual testing +3. ln-350-story-test-planner → Creates Story Finalizer test task +4. ln-334-test-executor → Implements all tests (E2E, Integration, Unit) + +**Rationale**: Atomic testing strategy, prevents test duplication, ensures comprehensive coverage. + +#### Documentation + +**Rule**: Documentation is ALWAYS integrated in feature tasks (same task as implementation). + +**NEVER** create: +- Separate documentation tasks +- "Update README" tasks +- "Write API docs" tasks + +**Process**: Implementation task includes both code AND documentation updates in Definition of Done. + +**Rationale**: Ensures documentation stays in sync with code, prevents documentation debt. + +--- + +### Rule 3: Story-Level Test Strategy + +**Value-Based Testing**: Test only scenarios with Priority ≥15 (calculated by Impact × Likelihood). + +**Test Limits per Story**: + +| Test Type | Min | Max | Purpose | +|-----------|-----|-----|---------| +| **E2E Tests** | 2 | 5 | End-to-end user workflows (Priority ≥15) | +| **Integration Tests** | 3 | 8 | Component interactions, external APIs | +| **Unit Tests** | 5 | 15 | Business logic, edge cases | +| **Total** | 10 | 28 | Complete Story coverage | + +**Example**: +``` +Story: User Authentication +- E2E: 3 tests (login success, login failure, session expiry) +- Integration: 5 tests (OAuth flow, token refresh, database session storage, Redis cache, logout) +- Unit: 8 tests (password validation, email validation, token generation, permission checks, etc.) +Total: 16 tests (within 10-28 range) +``` + +**Reference**: [Risk-Based Testing Guide](../reference/guides/risk-based-testing-guide.md) for Priority calculation. + +--- + +### Rule 4: Context Budget Rule + +- [ ] **CRITICAL: Minimize context pollution in kanban_board.md** + +**Rule:** [kanban_board.md](./kanban_board.md) contains ONLY links and titles - no descriptions, no implementation notes. + +**Board Structure:** + +Single hierarchical view: **Status → Epic → User Story → Tasks** + +**Sections:** +1. **Work in Progress** - Hierarchical task tracking (Backlog → Todo → In Progress → To Review → To Rework → Done → Postponed) +2. **Epics Overview** - Portfolio-level status (Active + Completed epics) + +**Format Rules:** + +**User Story:** +- Format: `📖 [{{TEAM_KEY}}-XX: USYYY Title](link)` + optional `✅ APPROVED` +- 2-space indent from Epic +- Always shows parent epic context +- Can exist without tasks ONLY in Backlog status (with note: `_(tasks not created yet)_`) + +**Task:** +- Format: ` - [{{TEAM_KEY}}-XX: EPYY_ZZ Title](link)` (2-space indent + dash) +- 4-space total indent (2-space base from Story + 2-space for dash) +- Always nested under parent User Story +- Cannot exist without parent story + +**Epic Grouping:** +- Each status section grouped by: `**Epic N: Epic Name**` (bold header) +- Stories listed under epic with 2-space indent +- Tasks listed under stories with 4-space indent (2-space base + 2-space for dash) + +**Status-Specific Limits:** +- **Backlog:** All stories (tasks optional, use `_(tasks not created yet)_` if none) +- **Todo/In Progress/To Review/To Rework:** All stories with all tasks +- **Done:** Maximum 5 tasks total across all stories (show most recent) +- **Postponed:** All stories with all tasks + +**Rationale:** +- Single view eliminates need to "jump" between sections +- Natural hierarchy matches mental model: Status → Epic → Story → Task +- Story context always visible with its tasks +- Reduced cognitive load: one structure, not three +- Minimize context size for AI agents +- Fast navigation at all levels (status/epic/story/task) + +--- + +## Task Workflow + +### Planning Guidelines + +**Optimal Task Size**: 3-5 hours per task + +**Task Granularity**: +- Too small (< 2 hours): Merge with related tasks +- Too large (> 8 hours): Split into subtasks +- Sweet spot (3-5 hours): Maximum productivity, clear acceptance criteria + +**Story Limits**: +- Implementation tasks: 1-6 tasks per Story +- Test task: 1 Story Finalizer test task (created after implementation) +- Total: Max 7 tasks per Story + +### Workflow Skills + +| Category | Skill | Purpose | +|----------|-------|---------| +| **Planning** | ln-210-epic-coordinator | Decompose scope → 3-7 Epics | +| | ln-220-story-coordinator | Decompose Epic → 5-10 Stories (with Phase 3 Library Research) | +| | ln-310-story-decomposer | Decompose Story → 1-6 Implementation Tasks | +| | ln-350-story-test-planner | Plan Story Finalizer test task (after manual testing) | +| **Validation** | ln-320-story-validator | Auto-fix Stories/Tasks → Approve (Backlog → Todo) | +| **Execution** | ln-330-story-executor | Orchestrate Story execution (delegates to ln-31/ln-34/ln-32) | +| | ln-331-task-executor | Execute implementation tasks (Todo → In Progress → To Review) | +| | ln-334-test-executor | Execute Story Finalizer test tasks (11 sections) | +| | ln-332-task-reviewer | Review tasks (To Review → Done/Rework) | +| | ln-333-task-rework | Fix tasks after review (To Rework → To Review) | +| **Quality** | ln-340-story-quality-gate | Two-pass review (Code Quality → Regression → Manual Testing) | +| | ln-341-code-quality-checker | Analyze code for DRY/KISS/YAGNI violations | +| | ln-342-regression-checker | Run existing test suite | +| | ln-343-manual-tester | Perform manual testing via curl/puppeteer | +| **Documentation** | ln-114-project-docs-creator | Create project docs (requirements, architecture, specs) | +| | ln-322-adr-creator | Create ADRs (architecture decisions) | +| | ln-321-guide-creator | Create guides (reusable patterns) | +| | ln-323-manual-creator | Create manuals (API references) | + +--- + +## Project Configuration + +### Quality Commands + +```bash +# Docker development environment +{{DOCKER_COMMAND}} + +# Run tests +{{TEST_COMMAND}} + +# Run tests with coverage +{{COVERAGE_COMMAND}} + +# Type checking +{{TYPE_CHECK_COMMAND}} + +# Linting +{{LINT_COMMAND}} +``` + +### Documentation Structure + +Core documentation: +- [Requirements](../project/requirements.md) - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization +- [Architecture](../project/architecture.md) - System architecture (C4 Model, arc42) +- [Technical Specification](../project/technical_specification.md) - Implementation details +- [ADRs](../reference/adrs/) - Architecture Decision Records +- [Guides](../reference/guides/) - Project patterns and best practices +- [Manuals](../reference/manuals/) - Package API references + +### Label Taxonomy + +**Functional Labels**: `feature`, `bug`, `refactoring`, `documentation`, `testing`, `infrastructure` + +**Type Labels**: `user-story`, `implementation-task`, `test-task` + +**Status Labels** (auto-managed by Linear): `backlog`, `todo`, `in-progress`, `to-review`, `to-rework`, `done`, `canceled` + +### Test Audit History (Optional) + +**Test Audit:** Every +50 tests → review new files, delete framework tests. Last: {{AUDIT_DATE}} ({{OLD_COUNT}} → {{NEW_COUNT}}) + +--- + +## Linear MCP Methods Reference + +### Core Operations + +**Issues**: + +```python +# List issues +mcp__linear-server__list_issues( + team="TeamName", # Team name or ID + state="In Progress", # State name or ID + assignee="me", # User ID, name, email, or "me" + limit=50 # Max 250 +) + +# Get issue details +mcp__linear-server__get_issue( + id="PROJ-123" # Issue ID +) + +# Create issue +mcp__linear-server__create_issue( + team="TeamName", # Required: Team name or ID + title="Task title", # Required: Issue title + description="...", # Markdown description + state="Todo", # State name or ID + assignee="me", # User ID, name, email, or "me" + parentId="parent-uuid", # For tasks (parent Story UUID) + labels=["feature", "backend"] # Label names or IDs +) + +# Update issue +mcp__linear-server__update_issue( + id="PROJ-123", # Required: Issue ID + state="Done", # State name or ID + description="...", # Updated description + assignee="me" # Reassign +) +``` + +**Projects** (Epics): + +```python +# List projects +mcp__linear-server__list_projects( + team="TeamName", # Filter by team + state="started", # Filter by state + limit=50 +) + +# Get project +mcp__linear-server__get_project( + query="Epic 1" # ID or name +) + +# Create project (Epic) +mcp__linear-server__create_project( + team="TeamName", # Required + name="Epic 1: Auth", # Required + description="...", # Epic description + state="planned" # Epic state +) + +# Update project +mcp__linear-server__update_project( + id="project-uuid", # Required + state="started", # Update state + description="..." # Update description +) +``` + +**Teams**: + +```python +# List teams +mcp__linear-server__list_teams() + +# Get team +mcp__linear-server__get_team( + query="TeamName" # UUID, key, or name +) +``` + +**Labels**: + +```python +# List labels +mcp__linear-server__list_issue_labels( + team="TeamName" # Optional: filter by team +) + +# Create label +mcp__linear-server__create_issue_label( + name="backend", # Required + color="#FF5733", # Hex color + teamId="team-uuid" # Optional: team-specific label +) +``` + +**Comments**: + +```python +# List comments +mcp__linear-server__list_comments( + issueId="issue-uuid" # Required +) + +# Create comment +mcp__linear-server__create_comment( + issueId="issue-uuid", # Required + body="Comment text" # Required: Markdown +) +``` + +### Parameter Patterns + +**Common Filters**: + +```python +# By assignee +assignee="me" # Current user +assignee="user@example.com" # By email +assignee="user-uuid" # By UUID + +# By state +state="Todo" # By name +state="state-uuid" # By UUID + +# By team +team="TeamName" # By name +team="team-uuid" # By UUID + +# By label +label="feature" # By name +label="label-uuid" # By UUID +``` + +**Pagination**: + +```python +# Limit results +limit=50 # Default: 50, Max: 250 + +# Pagination +after="cursor-id" # Start from cursor +before="cursor-id" # End at cursor +``` + +**Date Filters**: + +```python +# ISO-8601 date-time +createdAt="2025-01-01T00:00:00Z" + +# Duration (relative) +createdAt="-P1D" # Created in last 1 day +updatedAt="-P7D" # Updated in last 7 days +``` + +### Examples + +**Example 1: Get all In Progress tasks for current user** + +```python +issues = mcp__linear-server__list_issues( + team="ProjectTeam", + state="In Progress", + assignee="me", + limit=100 +) +``` + +**Example 2: Create Story (User Story)** + +```python +story = mcp__linear-server__create_issue( + team="ProjectTeam", + title="US001 User Login", + description="User story description...", + state="Backlog", + labels=["user-story", "feature"] +) +``` + +**Example 3: Create Task (child of Story)** + +```python +task = mcp__linear-server__create_issue( + team="ProjectTeam", + title="EP1_01 Implement JWT tokens", + description="Task description...", + state="Todo", + parentId="story-uuid", # Link to parent Story + labels=["implementation-task", "backend"] +) +``` + +**Example 4: Move task to Done** + +```python +mcp__linear-server__update_issue( + id="PROJ-123", + state="Done" +) +``` + +**Example 5: Create Epic (Project)** + +```python +epic = mcp__linear-server__create_project( + team="ProjectTeam", + name="Epic 1: Authentication System", + description="Epic description...", + state="planned" +) +``` + +--- + +## Maintenance + +**Update Triggers**: +- When adding new workflow skills +- When changing task lifecycle statuses +- When updating Critical Rules +- When modifying Linear integration patterns +- When changing test strategy limits + +**Verification**: +- All Linear MCP method examples are valid +- Workflow skills table matches available skills +- Critical Rules align with current development principles +- Test limits match risk-based testing guide + +**Last Updated**: {{DATE}} + +--- + +**Template Version:** 1.0.0 +**Template Last Updated:** 2025-11-15 diff --git a/skills/ln-114-project-docs-creator/SKILL.md b/skills/ln-114-project-docs-creator/SKILL.md new file mode 100644 index 0000000..f1bb21c --- /dev/null +++ b/skills/ln-114-project-docs-creator/SKILL.md @@ -0,0 +1,457 @@ +--- +name: ln-114-project-docs-creator +description: Creates and validates 7 project docs (requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook). Fourth worker in ln-110-documents-pipeline. +--- + +# Project Documentation Creator + +This skill creates and validates technical project documentation following industry best practices (ISO/IEC/IEEE standards, arc42, C4 Model, ADR format). + +## When to Use This Skill + +**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator. + +This skill should be used directly when: +- Creating only project documentation (7 docs: requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook) +- Validating existing project documentation +- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup) + +**Part of workflow**: ln-110-documents-pipeline (orchestrator) → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → **ln-114-project-docs-creator** → ln-115-presentation-creator → ln-116-test-docs-creator + +## How It Works + +The skill follows a 4-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT** → **FINALIZE**. Each phase builds on the previous, ensuring complete structure and semantic validation. + +--- + +### Phase 1: Create Structure + +**Objective**: Establish project documentation files (3-7 files based on project type). + +**Process**: + +**1.1 Check existing files**: +- Use Glob to scan `docs/project/*.md` +- Check which of 7 project docs already exist: + - requirements.md (ALWAYS needed) + - architecture.md (ALWAYS needed) + - tech_stack.md (ALWAYS needed) + - api_spec.md (Backend/Full-stack only) + - database_schema.md (if database detected) + - design_guidelines.md (Frontend/Full-stack only) + - runbook.md (Docker-based projects) +- Build list of MISSING files + +**1.2 Determine conditional templates**: +- **api_spec.md**: Create if Backend/Full-stack project + - Detect: Check package.json for backend frameworks (express, fastify, nestjs) OR python/go/java runtime + - Skip for Frontend-only projects +- **database_schema.md**: Create if database detected + - Detect: Check package.json for database libraries (pg, mongoose, mysql2, sqlite3, prisma) + - Skip if no database found +- **design_guidelines.md**: Create if Frontend framework detected + - Detect: Check package.json for frontend frameworks (react, vue, angular, svelte, next) + - Skip for Backend-only projects + +**1.3 Create missing templates**: +- For each missing file, use Write tool to create from `references/templates/`: + - `requirements_template.md` → `docs/project/requirements.md` (if missing) + - `architecture_template.md` → `docs/project/architecture.md` (if missing) + - `tech_stack_template.md` → `docs/project/tech_stack.md` (if missing) + - `api_spec_template.md` → `docs/project/api_spec.md` (if missing and needed) + - `database_schema_template.md` → `docs/project/database_schema.md` (if missing and needed) + - `design_guidelines_template.md` → `docs/project/design_guidelines.md` (if missing and needed) + - `runbook_template.md` → `docs/project/runbook.md` (if missing) +- Track created file list (for Phase 2-3 validation) + +**1.4 Log summary**: +``` +✓ Project documentation structure: + - Created: X new files + - Preserved: Y existing files + - Skipped: Z conditional files (not needed for this project type) +``` + +**Output**: +``` +docs/project/ +├── requirements.md (created or existing) +├── architecture.md (created or existing) +├── tech_stack.md (created or existing) +├── api_spec.md (created or existing, conditional) +├── database_schema.md (created or existing, conditional) +├── design_guidelines.md (created or existing, conditional) +└── runbook.md (created or existing, conditional) +``` + +--- + +### Phase 2: Validate Structure + +**Objective**: Ensure project documentation complies with structural requirements and auto-fix violations. + +**Process**: + +**2.1 Check SCOPE tags** (all created files): +- Read first 5 lines of each file created in Phase 1 +- Check for `` tag +- Expected patterns: + - requirements.md: `` + - architecture.md: `` + - tech_stack.md: `` + - api_spec.md: `` + - database_schema.md: `` + - design_guidelines.md: `` + - runbook.md: `` +- If missing: + - Use Edit tool to add SCOPE tag at line 1 (after first heading) + - Track violation count +- Log: "✓ SCOPE tags: [added N/all present]" + +**2.2 Check required sections** (from questions.md): +- Load `references/questions.md` using Read tool +- For each document created in Phase 1: + - Extract expected sections from questions.md + - Check if section headers exist in document + - If missing: + - Use Edit tool to add section with placeholder + - Track violation count +- Examples: + - requirements.md: ## Functional Requirements + - architecture.md: ## 1. Introduction and Goals, ## 2. Constraints, ..., ## 11. Glossary + - tech_stack.md: ## Frontend Technologies, ## Backend Technologies, ## Database, ## Additional Technologies +- Log: "✓ Required sections: [added N sections across M files/all present]" + +**2.3 Check Maintenance section** (all created files): +- Search for `## Maintenance` header in each file +- If missing: + - Use Edit tool to add at end of file: + ```markdown + ## Maintenance + + **Last Updated:** [current date] + + **Update Triggers:** + - [Document-specific triggers] + + **Verification:** + - [ ] All sections have content (no placeholders) + - [ ] Diagrams render correctly + - [ ] Links to other docs are valid + ``` + - Track violation count +- Log: "✓ Maintenance sections: [added N/all present]" + +**2.4 Check POSIX file endings** (all created files): +- Check if each file ends with single blank line +- If missing: + - Use Edit tool to add final newline + - Track fix count +- Log: "✓ POSIX compliance: [fixed N files/all compliant]" + +**2.5 Conditional checks**: +- **api_spec.md**: Only validate if Backend/Full-stack project detected + - Skip validation if Frontend-only project + - Log: "ℹ api_spec.md skipped (Frontend-only project)" +- **database_schema.md**: Only validate if database detected in dependencies + - Check package.json for database libraries (pg, mongoose, mysql2, sqlite3) + - Skip if no database found + - Log: "ℹ database_schema.md skipped (no database detected)" +- **design_guidelines.md**: Only validate if Frontend framework detected + - Check package.json for frontend frameworks (react, vue, angular, svelte) + - Skip if Backend-only project + - Log: "ℹ design_guidelines.md skipped (Backend-only project)" + +**2.6 Report validation**: +- Log summary: + ``` + ✅ Structure validation complete: + - SCOPE tags: [added N/all present] + - Missing sections: [added N sections across M files/all present] + - Maintenance sections: [added N/all present] + - POSIX endings: [fixed N files/all compliant] + - Conditional checks: [skipped K files based on project type] + ``` +- If violations found: "⚠️ Auto-fixed [total] structural violations" + +--- + +### Phase 3: Validate Content + +**Objective**: Ensure each section answers its questions with meaningful content using semantic validation. + +**Process**: + +**3.1 Load validation spec**: +- Read `references/questions.md` using Read tool +- Parse all 27 questions with validation heuristics, auto-discovery hints, and MCP Ref hints +- Build validation map: {document → [{question, section, heuristics, auto_discovery, mcp_ref}]} + +**3.2 Validate sections** (parametric loop for ~27 questions): + +For each question in questions.md: + +1. **Extract section content**: + - Read target document (requirements.md, architecture.md, etc.) + - Extract section content between headers + - If section missing → error (should have been added in Phase 2.2) + +2. **Check if content answers question**: + - Apply validation heuristics from questions.md + - Examples: + - "Has FR-XXX identifiers" → scan for pattern `FR-\w+-\d+` + - "Length > 100 words" → count words in section + - "Has Mermaid diagram" → check for ```mermaid code blocks + - If ANY heuristic passes → content valid, skip to next question + - If ALL fail → content invalid, continue + +3. **Auto-discovery** (if content invalid or has placeholders): + - Execute auto-discovery hints from questions.md + - Examples: + - **package.json scanning**: + - Read package.json + - Extract dependencies, devDependencies, scripts, engines, version + - Identify frameworks (react → Frontend, express → Backend) + - **src/ directory structure**: + - Scan src/ using Glob tool + - Detect architecture patterns: + - `src/controllers/`, `src/services/`, `src/repositories/` → Layered architecture + - `src/modules/`, `src/features/` → Modular architecture + - `src/pages/`, `src/components/` → Frontend component structure + - **docker-compose.yml**: + - Read docker-compose.yml if exists + - Extract services (postgres, mongo, redis, rabbitmq) + - Populate tech_stack.md and database_schema.md sections + - **.env.example**: + - Read .env.example if exists + - Extract configuration variables + - Populate runbook.md environment variables section + - **migrations/ directory**: + - Scan migrations/ or db/migrations/ + - Extract table names from CREATE TABLE statements + - Populate database_schema.md tables section + - If auto-discovery successful: + - Use Edit tool to populate section with discovered data + - Track change: `sections_populated += 1` + - Skip MCP Ref and user questions + - If auto-discovery fails → continue to MCP Ref + +4. **MCP Ref research** (if auto-discovery fails): + - Execute MCP Ref hints from questions.md + - Examples: + - Framework features: `mcp__context7__resolve-library-id("React")` → `mcp__context7__get-library-docs("/facebook/react", topic="React 18 features")` + - Architecture patterns: `mcp__Ref__ref_search_documentation("Layered architecture vs microservices")` + - Library standards: `mcp__Ref__ref_search_documentation("Repository pattern best practices")` + - Technology comparison: `mcp__Ref__ref_search_documentation("PostgreSQL vs MongoDB comparison")` + - If research yields useful information: + - Use Edit tool to populate section with research summary + - Track change: `sections_researched += 1` + - Skip user questions + - If research fails → continue to user fallback + +5. **User question fallback** (if auto-discovery AND MCP Ref fail): + - Ask user the question from questions.md + - Examples: + - "What are the main functional requirements?" (if no hints found) + - "What are the system quality goals?" (if no constraints discovered) + - "What is the primary architecture pattern?" (if src/ structure ambiguous) + - Wait for user response + - Use Edit tool to populate section with user's answer + - Track change: `sections_user_input += 1` + +6. **Track validation result**: + - Log per question: "[Document] Section X: [valid/populated via auto-discovery/populated via MCP Ref/populated via user input]" + +**3.3 Priority-based validation** (optimize token usage): +- **Critical priority** (requirements.md, architecture.md, runbook.md): + - Validate all sections + - Ask user questions if auto-discovery/MCP Ref fail +- **High priority** (tech_stack.md, api_spec.md, database_schema.md): + - Validate all sections + - Prefer auto-discovery and MCP Ref + - Only ask critical user questions +- **Medium priority** (design_guidelines.md): + - Validate required sections only + - Skip if Frontend-only and user confirms can use template defaults + +**3.4 Report content validation**: +- Log summary: + ``` + ✅ Content validation complete: + - Questions checked: 27 (or 22 for backend-only, 24 for frontend-only) + - Already valid: [count] sections + - Populated via auto-discovery: [count] sections + - Populated via MCP Ref: [count] sections + - Populated via user input: [count] sections + - Placeholders kept: [count] sections (optional content) + ``` + +**Auto-discovery success rate example**: +``` +Full-stack Node.js project with package.json + docker-compose.yml: +- Auto-discovery: ~18/27 questions (67%) +- MCP Ref: ~5/27 questions (18%) +- User input: ~4/27 questions (15%) +``` + +--- + +### Phase 4: Finalization + +**Objective**: Provide complete overview and next steps. + +**Process**: +1. List all project files with status (3-7 files depending on project type): + - `docs/project/requirements.md` (ALWAYS) - created or preserved + - `docs/project/architecture.md` (ALWAYS) - created or preserved + - `docs/project/tech_stack.md` (ALWAYS) - created or preserved + - `docs/project/api_spec.md` (if API/Backend/Full-stack) - created or preserved + - `docs/project/database_schema.md` (if uses database) - created or preserved + - `docs/project/design_guidelines.md` (if Frontend/Full-stack) - created or preserved + - `docs/project/runbook.md` (if Docker-based) - created or preserved + +2. Report summary: + - "✓ Project documentation complete: Created X new files, preserved Y existing" + - "Validation: Structure [N fixes], Content [M updates]" + +**Output**: Summary message with project files status (created vs preserved) + +--- + +## Complete Output Structure + +``` +docs/ +└── project/ + ├── requirements.md # Functional Requirements (FR-XXX-NNN) ONLY + ├── architecture.md # arc42-based architecture with C4 Model + ├── tech_stack.md # Technology stack, versions, Docker setup + ├── api_spec.md # API endpoints, auth, error codes (conditional) + ├── database_schema.md # ER diagrams, tables, migrations (conditional) + ├── design_guidelines.md # UI/UX design system (conditional - frontend only) + └── runbook.md # Operations: local/testing/production (conditional) +``` + +**Conditional files:** +- `api_spec.md` - Created for API/Backend/Full-stack projects +- `database_schema.md` - Created if project uses database (PostgreSQL, MySQL, MongoDB, etc.) +- `design_guidelines.md` - Created for Frontend/Full-stack projects (skipped for backend-only) +- `runbook.md` - Created for Docker-based projects + +--- + +## Reference Files Used + +### Document Templates + +**Project Document Templates** (used in Phase 1 from `references/templates/`): +- `requirements_template.md` - Functional Requirements ONLY (ISO/IEC/IEEE 29148:2018) +- `architecture_template.md` - arc42-based architecture with C4 Model (ISO/IEC/IEEE 42010:2022) +- `tech_stack_template.md` - Technology stack, versions, Docker configuration +- `api_spec_template.md` - API specification (OpenAPI 3.0 compatible) +- `database_schema_template.md` - ER diagrams, data dictionary, migrations +- `design_guidelines_template.md` - UI/UX design system (WCAG 2.1 Level AA) +- `runbook_template.md` - Operations guide (local/testing/production) + +**Validation Specification**: +- `references/questions.md` (v1.0) - 27 questions with validation heuristics: + - Questions each section must answer + - Validation heuristics (checkable criteria) + - Auto-discovery hints (package.json, src/, docker-compose.yml, migrations/) + - MCP Ref hints (external research topics) + +--- + +## Best Practices + +- **Idempotent Operations**: ✅ Checks file existence before creation (Phase 1), creates only missing files, preserves existing project docs +- **Conditional Templates**: Only create templates relevant to project type (skip design_guidelines.md for backend-only, skip api_spec.md for frontend-only) +- **Parametric Validation**: Phase 3 uses loop for 27 questions (no code duplication) +- **Auto-discovery First**: Scan actual files before external API calls or user questions +- **Separation of Concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT → FINALIZE +- **Document Generation**: English only, explicit IDs (FR-XXX-001), MoSCoW prioritization, meaningful Mermaid diagrams with actual data +- **Token Efficiency**: Reuse discovered data across multiple documents, avoid asking same questions twice + +--- + +## Prerequisites + +**Invoked by**: ln-110-documents-pipeline orchestrator + +**Requires**: +- `docs/` directory (created by ln-111-root-docs-creator) + +**Creates**: +- `docs/project/` directory structure (3-7 files) +- Validated project documentation with structure and content checks + +**Idempotent**: ✅ Can be invoked multiple times safely +- Checks file existence before creation +- Skips existing files +- Re-validates on subsequent runs + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +**✅ Documents Generated:** +- [ ] All required project documents created successfully (3-7 files depending on project type): + - `docs/project/requirements.md` (ALWAYS) + - `docs/project/architecture.md` (ALWAYS) + - `docs/project/tech_stack.md` (ALWAYS) + - `docs/project/api_spec.md` (if API/Backend/Full-stack) + - `docs/project/database_schema.md` (if uses database) + - `docs/project/design_guidelines.md` (if Frontend/Full-stack) + - `docs/project/runbook.md` (if Docker-based) +- [ ] SCOPE tags included in first 3-5 lines of each document +- [ ] Maintenance sections present in all docs +- [ ] All placeholders replaced with actual content (no `{{PLACEHOLDER}}` remaining) + +**✅ Content Quality:** +- [ ] Mermaid diagrams valid syntax (Business Context, Technical Context, C4 diagrams, ER diagrams) +- [ ] Requirement IDs sequential and unique (FR-XXX-001 only) +- [ ] MoSCoW prioritization applied correctly (MUST/SHOULD/COULD/WON'T) +- [ ] Language: English only (per project standards) +- [ ] Docker configuration present in tech_stack.md + +**✅ Phase Completion:** +- [ ] Phase 1: Create Structure completed + - [ ] Conditional templates determined (api_spec, database_schema, design_guidelines) + - [ ] Missing files created (3-7 based on project type) + - [ ] Created file list tracked +- [ ] Phase 2: Validate Structure completed + - [ ] SCOPE tags verified/added (all created files) + - [ ] Required sections verified/added (from questions.md) + - [ ] Maintenance sections verified/added (all created files) + - [ ] POSIX file endings verified/fixed + - [ ] Conditional checks performed (api_spec, database_schema, design_guidelines) +- [ ] Phase 3: Validate Content completed + - [ ] questions.md loaded for semantic validation + - [ ] All 27 questions validated (or 22/24 for specific project types) + - [ ] Auto-discovery executed where applicable + - [ ] MCP Ref research executed where needed + - [ ] User fallback questions asked for critical content + - [ ] Content validation report generated +- [ ] Phase 4: Finalization completed + - [ ] Summary displayed with file paths and status + +**✅ User Guidance:** +- [ ] Summary message displayed with all file paths +- [ ] User informed: "✓ Project documentation complete (X files created)" + +**Output:** Complete project documentation set in `docs/project/` (3-7 MD docs depending on project type) + +--- + +## Technical Details + +**Standards**: ISO/IEC/IEEE 29148:2018 (Requirements), ISO/IEC/IEEE 42010:2022 (Architecture), arc42, C4 Model, MoSCoW Prioritization, OWASP Security, WCAG 2.1 Level AA + +**Language**: English only + +--- + +**Version:** 12.0.0 (MAJOR: Merged validation into worker. Added Phase 2 structure validation + Phase 3 semantic content validation with extensive auto-discovery (package.json, src/, docker-compose.yml, migrations/) and MCP Ref research. Idempotent - can be invoked multiple times.) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-114-project-docs-creator/diagram.html b/skills/ln-114-project-docs-creator/diagram.html new file mode 100644 index 0000000..9d39a4c --- /dev/null +++ b/skills/ln-114-project-docs-creator/diagram.html @@ -0,0 +1,129 @@ + + + + + + ln-114-project-docs-creator - State Diagram + + + + +
+
+

📚 ln-114-project-docs-creator

+

Project Documentation Creator - State Diagram

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Create and validate 7 project docs (requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook)
    • +
  • Worker for: ln-110-documents-pipeline orchestrator
    • +
  • Phases: 4 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Content Validation → Phase 4 Finalization)
    • +
  • Validation: 27 questions with auto-discovery → MCP Ref → user fallback hierarchy
    • +
  • Auto-Discovery: package.json, src/ structure, docker-compose.yml, migrations/, .env.example scanning
    • +
+
+ +
+
+
+ Creation Action +
+
+
+ Validation +
+
+
+ Decision Point +
+
+ +
+
+graph TD + Start([Start: Create Project Documentation]) --> Phase1[Phase 1: Create Structure
3-7 files based on project type] + + Phase1 --> CheckFiles[Check existing files
docs/project/*.md] + CheckFiles --> DetermineTemplates[Determine conditional templates:
api_spec Backend only
database_schema if DB detected
design_guidelines Frontend only] + DetermineTemplates --> CreateMissing[Create missing templates from references/] + + CreateMissing --> Phase2[Phase 2: Validate Structure
Auto-fix violations] + + Phase2 --> AutoFix[Auto-fix:
SCOPE tags, required sections,
Maintenance sections, POSIX endings] + + AutoFix --> Phase3[Phase 3: Validate Content
27 questions parametric loop] + + Phase3 --> ParametricLoop[For each question in questions.md:
Extract section content] + + ParametricLoop --> CheckHeuristics{Validation
heuristics pass?} + CheckHeuristics -->|Yes| Valid[Section valid, skip to next question] + CheckHeuristics -->|No| AutoDiscovery + + AutoDiscovery[Auto-discovery:
package.json, src/, docker-compose,
migrations/, .env.example] + AutoDiscovery --> DiscoverySuccess{Discovery
successful?} + DiscoverySuccess -->|Yes| PopulateDiscovery[Populate section
with discovered data] + DiscoverySuccess -->|No| MCPRef + + MCPRef[MCP Ref research:
Framework features, architecture patterns,
library standards, tech comparisons] + MCPRef --> MCPSuccess{Research
successful?} + MCPSuccess -->|Yes| PopulateRef[Populate section
with research summary] + MCPSuccess -->|No| UserFallback[User question fallback:
Ask user to provide content] + + PopulateDiscovery --> MoreQuestions + PopulateRef --> MoreQuestions + UserFallback --> MoreQuestions + Valid --> MoreQuestions + + MoreQuestions{More questions
to validate?} + MoreQuestions -->|Yes| ParametricLoop + MoreQuestions -->|No| Phase4 + + Phase4[Phase 4: Finalization
Generate summary report] + Phase4 --> Summary[Display completion summary:
Files created/preserved,
Sections populated auto vs user] + + Summary --> End([End: ✓ 7 project docs created + validated]) + + %% Styling + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px + classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px + + class Phase1,CheckFiles,DetermineTemplates,CreateMissing,AutoFix,PopulateDiscovery,PopulateRef,UserFallback,Summary action + class Phase2,Phase3,ParametricLoop,AutoDiscovery,MCPRef,Phase4 validation + class CheckHeuristics,DiscoverySuccess,MCPSuccess,MoreQuestions decision +
+
+ +
+

🔑 Key Features

+
    +
  • Fourth Worker: Creates project documentation after task management system (ln-110 → ln-111 → ln-112 → ln-113 → ln-114)
    • +
  • Conditional Templates: api_spec.md (Backend/Full-stack), database_schema.md (if DB detected), design_guidelines.md (Frontend/Full-stack)
    • +
  • 3-Level Validation Hierarchy: Auto-discovery (67%) → MCP Ref (18%) → User input (15%) for optimal token efficiency
    • +
  • Priority-Based Validation: Critical (requirements, architecture, runbook) → High (tech_stack, api_spec, database_schema) → Medium (design_guidelines)
    • +
  • Smart Auto-Discovery: Scans package.json, src/ directory structure, docker-compose.yml, migrations/, .env.example
    • +
  • Parametric Loop: 27 questions with validation heuristics, auto-discovery hints, MCP Ref hints
    • +
+
+ +
+

Generated for ln-114-project-docs-creator skill | Version 12.0.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-18

+
+
+ + + + diff --git a/skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md b/skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md new file mode 100644 index 0000000..2aa3c74 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md @@ -0,0 +1,206 @@ +# Automatic Analysis Guide + +Guide for automatic analysis of project materials and researching 2025 best practices. + +--- + +## Section 1: Analyzing Project Materials + +### When to Analyze +Ask user: *"Do you have project materials to analyze? (files, diagrams, docs, code)"* + +### Files to Search (use Glob + Read) + +**Package managers**: `package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Gemfile` +**Docker**: `Dockerfile`, `docker-compose.yml`, `docker-compose.test.yml` +**Config**: `tsconfig.json`, `*.env.example`, `.nvmrc` +**Docs**: `README.md`, architecture diagrams +**Code structure**: `src/`, `api/`, `services/`, `tests/` + +### Information to Extract + +From **package.json / requirements.txt / go.mod**: +- Runtime version (Node 18, Python 3.11, Go 1.21) +- Dependencies → frameworks, databases, auth, cache +- Pre-populate: Q9, Q12 + +From **Dockerfile**: +- Base image → runtime version +- Multi-stage structure → build optimization +- Pre-populate: Q9, Q12 + +From **docker-compose.yml**: +- Services → app + db + cache + queue +- Images → database/cache versions +- Volumes → hot-reload setup +- Pre-populate: Q9, Q11 + +From **docker-compose.test.yml**: +- Test services → db-test, cache-test (isolated) +- Volumes → ./src, ./tests (hot-reload) +- Tmpfs → in-memory test databases +- Command → test framework +- Pre-populate: Q12 (test setup) + +### Output Format +``` +✓ Analyzed project materials + +**Detected**: +- Runtime: [runtime + version] +- Framework: [framework + version] +- Database: [database] +- Architecture: [hints from docker-compose] + +**Pre-populated**: Q9, Q12 (partial) +``` + +--- + +## Section 2: Researching Best Practices 2025 + +### When to Research +During **Phase 2, Stage 2** for questions Q9, Q11-Q13. + +Ask user first: *"Research best practices automatically? (Y/N)"* + +### Research Tools + +**MCP Ref** (`mcp__Ref__ref_search_documentation`): +- Query: `"[framework] latest version 2025"` +- Use for: Official docs, version numbers, features +- Then Read: `mcp__Ref__ref_read_url` for details + +**WebSearch**: +- Query patterns: + - `"[Tech A] vs [Tech B] 2025 comparison"` + - `"best practices [technology] 2025"` + - `"[pattern] architecture pros cons 2025"` +- Use for: Comparisons, best practices, trends + +### Research Strategy by Question + +**Q9: Technology Decisions** +1. Check analyzed versions vs 2025 latest +2. MCP Ref: latest stable versions +3. WebSearch: security vulnerabilities, release notes +4. Recommend upgrades if: EOL, security issues, LTS available + +**Q11: Architectural Patterns** +1. Identify project type + scale from Stage 1 +2. WebSearch: `"[project type] architecture patterns 2025"` +3. Consider scale: + - Small (< 10K users) → Monolith + - Medium (10K-100K) → Microservices + - Large (100K+) → Microservices + Event-Driven + +**Q12: Libraries and Frameworks** +1. Based on Q9 + Q11 +2. MCP Ref: latest versions for each component +3. WebSearch: compatibility, comparisons +4. Check: ORM, testing framework, validation library +5. Verify compatibility matrix + +**Q13: Integrations** +1. Identify needs from Q5 (IN SCOPE) +2. WebSearch comparisons: + - Payments: `"Stripe vs PayPal 2025"` + - Email: `"SendGrid vs AWS SES 2025"` + - Auth: `"Auth0 vs Clerk 2025"` + - Storage: `"AWS S3 vs Cloudinary 2025"` +3. Consider: pricing, DX, compliance, popularity + +### Dockerfile Generation +Based on Q12 runtime + framework: +- Latest stable base image +- Multi-stage build (dev + prod) +- Security: non-root user, minimal image +- Generate docker-compose.yml with services from Q11 + +--- + +## Section 3: Transition to Interactive Mode + +### When to Ask User + +**Pause research when**: +1. **Multiple alternatives** (React vs Vue) → present both, ask preference +2. **Insufficient info** (no files found) → ask directly +3. **Unclear goals** (vague Q5) → ask clarifying questions +4. **Always interactive**: Q10, Q14-Q19 (org-specific) + +### Alternative Presentation Template +``` +"Researched [Category]: + +**Option A**: [Tech A] +Pros: [key benefits] +Cons: [key drawbacks] + +**Option B**: [Tech B] +Pros: [key benefits] +Cons: [key drawbacks] + +Recommendation: [A/B] because [reason] + +Which do you prefer? (A/B/Other)" +``` + +### Fallback to Full Interactive +If no materials OR user declines research → ask all Q9-Q19 interactively + +--- + +## Section 4: Quality Guidelines + +### Verification Checklist +- [ ] Version is 2025-current (< 1 year old) +- [ ] Stable release (not beta) +- [ ] No critical security vulnerabilities +- [ ] Compatible with other tech +- [ ] Active community (GitHub stars, updates) +- [ ] Official docs available + +### Red Flags (Don't Recommend) +- Last updated > 2 years ago +- Unpatched security vulnerabilities +- Incompatible with stack +- Beta/experimental (unless requested) +- Obscure (<1000 GitHub stars) + +### Rationale Format +``` +Recommendation: [Technology] +Rationale: +1. [Technical reason] +2. [Ecosystem reason] +3. [Project fit reason] +4. [Industry adoption] +``` + +--- + +## Section 5: Execution Flow + +### Phase 1.5: Material Analysis +``` +User provides materials? (Y/N) +├─ Y: Glob + Read files → Extract info → Report findings +└─ N: Skip to Phase 2 +``` + +### Phase 2, Stage 2: Research & Design +``` +Stage 1 complete (Q1-Q8 answered) + ↓ +Research automatically? (Y/N) +├─ Y: Research Q9, Q11-Q13 → Present recommendations → User accepts/modifies +└─ N: Ask Q9-Q13 interactively + ↓ +Always ask Q10, Q14-Q19 interactively +``` + +--- + +**Version:** 1.0.0 +**Last Updated:** 2025-10-29 diff --git a/skills/ln-114-project-docs-creator/references/guides/critical_questions.md b/skills/ln-114-project-docs-creator/references/guides/critical_questions.md new file mode 100644 index 0000000..a93ac5d --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/guides/critical_questions.md @@ -0,0 +1,307 @@ +# Technical Questions for Project Documentation + +These 23 technical questions MUST be answered before creating project documentation. They are grouped into 6 categories for structured technical discovery. + +**Focus**: This document is **purely technical** - no business metrics, stakeholder management, or budget planning. For technical teams documenting architecture, requirements, and implementation details. + +## Priority Order: Context First, Questions Last + +**CRITICAL**: Interactive questions are the LAST RESORT. Follow this priority order: + +1. **Auto-Discovery (Phase 1.2)** - ALWAYS attempt first + - Search for: package.json, Dockerfile, docker-compose.yml, requirements.txt, pyproject.toml, pom.xml, build.gradle, go.mod, README.md + - Extract: Q9 (runtime versions), Q12 (frameworks, databases, dependencies) + - Benefits: Zero user effort, reduces questions by 2-4 + +2. **User Materials (Phase 1.3)** - MANDATORY question + - ALWAYS ask: "Do you have existing materials I should review? (design docs, specs, requirements, legacy docs, diagrams, API contracts)" + - If YES: Read and extract answers for Q1-Q23 from materials + - Benefits: Can reduce questions by 10-18 depending on material completeness + +3. **Best Practices Research (Phase 1.4)** - AUTO research + - Use MCP Ref to verify 2025 library versions (supplements Q12) + - Use WebSearch for architectural patterns (supplements Q11) + - Use WebSearch for integration best practices (supplements Q13) + - Benefits: Provides current best practices, reduces technical decision questions + +4. **Interactive Questions (Phase 2)** - ONLY for remaining questions + - Ask ONLY questions that could NOT be auto-discovered, extracted from materials, or researched + - Show progress: "Already gathered X/23 questions, asking Y remaining questions" + - Benefits: Minimizes user effort, maximizes efficiency + +**Example Impact**: +- Optimal scenario (with materials): 18/23 answered automatically → ask only 5 questions +- Typical scenario (no materials): 4/23 answered automatically → ask 19 questions +- Greenfield project: 6/23 answered from materials + research → ask 17 questions + +## Question Metadata (3-Stage Discovery) + +| Question | Category | Stage | Mode | Research Tools | +|----------|----------|-------|------|----------------| +| Q1-Q3 | Requirements | 1 | interactive | - | +| Q5-Q8 | Scope | 1 | interactive | - | +| Q9 | Tech Stack | 2 | auto-discoverable | package.json, Dockerfile, docker-compose.yml | +| Q10 | Tech Stack | 2 | interactive | - | +| Q11 | Tech Stack | 2 | auto-researchable | WebSearch | +| Q12 | Tech Stack | 2 | auto-discoverable + researchable | package.json + MCP Ref | +| Q13 | Tech Stack | 2 | auto-researchable | WebSearch | +| D1-D6 | Design Guidelines | 2 | interactive | - | +| O1-O3 | Operations | 2 | semi-auto | Dockerfile, docker-compose.yml | +| R1-R2 | Risks | 2 | interactive | - | + +**Stage 0 (Context Research - BEFORE asking questions)**: ALWAYS attempt auto-discovery (Q9, Q12 from package.json/Dockerfile), ALWAYS ask for user materials (may answer Q1-Q23), ALWAYS research best practices (Q11, Q13 via MCP Ref/WebSearch). This stage can reduce interactive questions by 20-75%. + +**Stage 1 (Understand Requirements)**: Ask REMAINING questions from Q1-Q3, Q5-Q8 that were NOT answered in Stage 0. Skip questions already extracted from materials. + +**Stage 2 (Research & Design)**: Ask REMAINING questions from Q10, D1-D6, O1-O3, R1-R2. Questions Q9, Q11, Q12, Q13 likely already answered in Stage 0 (auto-discovery + research). + +--- + +## Category 1: Requirements (3 questions) + +### Q1: What are the high-level technical acceptance criteria? +**Why important**: Defines what "done" looks like from a technical perspective. +**Example answer**: "Users can register via JWT auth, search products with <500ms latency, complete checkout with Stripe payment webhook handling" + +### Q2: What is the Minimum Viable Product (MVP) from a technical standpoint? +**Why important**: Defines Phase 1 technical scope and fastest path to functional system. +**Example answer**: "REST API with auth, CRUD for products, shopping cart in Redis, Stripe payment integration, PostgreSQL database" + +### Q3: Are all functional requirements technically defined and agreed? +**Why important**: Prevents mid-project requirement discovery and scope changes. +**Example answer**: "Yes, 15 functional requirements documented with IDs (FR-UM-001: User Registration, FR-PM-001: Product Listing, etc.) and technical acceptance criteria" + +--- + +## Category 2: Scope (4 questions) + +### Q5: What is technically IN SCOPE? +**Why important**: Defines technical boundaries and prevents misunderstandings about what will be built. +**Example answer**: "Microservices architecture (Product, Order, Payment services), PostgreSQL + Redis, REST API, JWT auth, Stripe integration, AWS ECS deployment" + +### Q6: What is technically OUT OF SCOPE? +**Why important**: Manages expectations and prevents technical feature creep. +**Example answer**: "No mobile native apps (web-responsive only), no AI/ML recommendations, no cryptocurrency payments, no GraphQL (REST only), no Kubernetes (ECS Fargate only)" + +### Q7: Where are the technical boundaries and integration points? +**Why important**: Clarifies interfaces with external systems and services. +**Example answer**: "External APIs: Stripe (payments), SendGrid (emails), AWS S3 (images). Internal: API Gateway routes to 4 microservices, Redis Pub/Sub for events" + +### Q8: Who are the technical user roles and what are their permissions? +**Why important**: Defines authentication and authorization requirements. +**Example answer**: "3 roles: Customer (browse, cart, checkout), Vendor (manage own products, view sales), Admin (platform config, user management)" + +--- + +## Category 3: Technology Stack (5 questions) + +### Q9: What technology decisions have already been made? +**Why important**: Identifies constraints and pre-existing technical commitments. +**Example answer**: "Must use: AWS (company standard), PostgreSQL (existing DBA expertise), Node.js (team skillset). Cannot use: MongoDB (no in-house experience)" + +### Q10: What are the hard technical constraints? +**Why important**: Defines non-negotiable limitations that affect architecture. +**Example answer**: "Must deploy to AWS us-east-1 (company policy), must comply with PCI DSS Level 1 (no card storage), cannot use Kubernetes (team lacks experience - use ECS Fargate), must integrate with legacy SOAP API (blocking dependency), cannot use serverless (compliance restrictions)" + +### Q11: What architectural patterns will be used? +**Why important**: Defines overall system structure and design approach. +**Example answer**: "Microservices architecture (4 services), Event-Driven communication (Redis Pub/Sub), REST API, Stateless services for horizontal scaling" + +### Q12: What libraries and frameworks will be used? +**Why important**: Defines technical stack and team training needs. +**Example answer**: "Frontend: React 18 + Next.js 14 + Tailwind CSS. Backend: Node.js 20 + Express + Prisma ORM. Testing: Jest + Supertest + Playwright" + +### Q13: What integrations with existing systems are required? +**Why important**: Identifies dependencies and integration complexity. +**Example answer**: "Integrate with: Legacy inventory system (SOAP API), Stripe (REST API), SendGrid (REST API), AWS S3 (SDK), existing user database (read-only PostgreSQL replica)" + +--- + +## Category 4: Design Guidelines (6 questions) + +### D1: What typography and color system should be used? +**Why important**: Defines visual consistency and brand identity for frontend projects. +**Example answer**: "Primary font: Inter (body), Poppins (headings). Colors: Primary #FF6B35 (orange), Secondary #004E89 (blue), Accent #1A936F (teal). WCAG 2.1 AA contrast ratios (4.5:1 text)" + +### D2: What component library and UI patterns should be implemented? +**Why important**: Ensures consistent user experience and speeds up development. +**Example answer**: "Buttons: Primary/Secondary/Text variants. Forms: Input fields with validation states. Cards: Default/Hover/Interactive. Modals: Backdrop + centered content. Tables: Sortable headers + pagination" + +### D3: What are the responsive breakpoints? +**Why important**: Defines how UI adapts across devices. +**Example answer**: "Mobile (<768px): 1-column stacked, Tablet (768-1024px): 2-column grid, Desktop (>1024px): 3-column grid + sidebar. Min tap target: 44x44px" + +### D4: What accessibility standards must be met? +**Why important**: Ensures inclusive design for users with disabilities. +**Example answer**: "WCAG 2.1 Level AA compliance: Keyboard navigation (all features), Screen reader support (ARIA labels), Color contrast 4.5:1 (text), Focus indicators (ring-2 ring-primary)" + +### D5: What branding and imagery guidelines apply? +**Why important**: Maintains consistent brand identity across the platform. +**Example answer**: "Logo: Min 32px height, clear space equals logo height. Hero images: 16:9 aspect ratio, min 1920x1080px. Stock photos: Professional, diverse, authentic (no clichés)" + +### D6: What design system or inspiration should be referenced? +**Why important**: Provides design direction and accelerates UI development. +**Example answer**: "Primary reference: Airbnb Design System (professional, user-friendly). Secondary influences: Material Design (components), Tailwind CSS (utility-first), Carbon Design (enterprise patterns)" + +--- + +## Category 5: Operations (3 questions) + +### O1: What is the development environment setup? +**Why important**: Defines how developers run the project locally. +**Example answer**: "Docker Compose with 5 services: app (Node.js), db (PostgreSQL), cache (Redis), queue (RabbitMQ), nginx (reverse proxy). Commands: `docker compose up -d`, `docker compose exec app npm run migrate`" + +### O2: What are the deployment procedures? +**Why important**: Defines how code reaches production safely. +**Example answer**: "CI/CD: GitHub Actions → Build Docker image → Push to ECR → Deploy to ECS Fargate (rolling update). Environments: Dev (auto-deploy main), Staging (manual approval), Production (manual approval + rollback plan)" + +### O3: What monitoring and troubleshooting tools are used? +**Why important**: Enables rapid incident detection and resolution. +**Example answer**: "Logs: CloudWatch Logs (centralized). Metrics: CloudWatch + Grafana dashboards (latency, errors, throughput). Alerts: PagerDuty (>5% error rate, p95 >500ms). SSH: Bastion host access for production debugging" + +--- + +## Category 6: Technical Risks (2 questions) + +### R1: What are the key technical risks? +**Why important**: Identifies potential technical failures that need mitigation. +**Example answer**: "Risk 1: Stripe outage blocks transactions (mitigation: retry logic + queue). Risk 2: Database becomes bottleneck (mitigation: read replicas + Redis caching). Risk 3: Microservice network failures (mitigation: circuit breakers + timeouts)" + +### R2: What are the critical technical dependencies? +**Why important**: Identifies external factors that could block or delay development. +**Example answer**: "Hard dependencies: AWS account approval (1 week), Stripe merchant account (2 weeks), Legacy API documentation (blocking integration). Team dependencies: 1 senior Node.js dev (key person risk)" + +--- + +## Question Priority Levels + +All 23 questions are **MUST-ANSWER** for complete technical documentation. Some questions (D1-D6) are frontend-specific and can be skipped for backend-only or API-only projects. + +--- + +## How to Use This Document + +**IMPORTANT**: Follow Priority Order (Context First, Questions Last) defined above. + +1. **Stage 0 - Context Research (Phase 1)**: + - **1.2 Auto-Discovery**: Use Glob to find package.json/Dockerfile/docker-compose.yml → Extract Q9, Q12 + - **1.3 User Materials**: ALWAYS ask "Do you have materials to review?" → Read and extract Q1-Q23 + - **1.4 Research**: Use MCP Ref for Q12 (2025 versions), WebSearch for Q11 (patterns), Q13 (integrations) + - **Track**: Mark which questions answered in Stage 0 + +2. **Stage 1-2 - Interactive Questions (Phase 2)**: + - **Review**: Display "Already gathered: X/23 questions" to user + - **Ask ONLY remaining**: Skip questions answered in Stage 0 + - **Batch questions**: Show progress "Category X of 6 (asking Y remaining questions)" + - **Capture Answers**: Record with question IDs for traceability + +3. **Map to Documents**: Use answers (from Stage 0 or Stage 1-2) to populate: + - `requirements.md` ← Q1, Q3 + - `architecture.md` ← Q5, Q6, Q7, Q9, Q10, Q11, Q12, Q13 + - `tech_stack.md` ← Q9, Q10, Q11, Q12 + - `api_spec.md` ← Q8, Q13 + - `database_schema.md` ← Q9, Q12 + - `design_guidelines.md` ← D1-D6 + - `runbook.md` ← O1-O3 + +4. **Validate Completeness**: Ensure all relevant questions have clear answers (skip D1-D6 for backend-only projects) +5. **Iterate if Needed**: If answers are unclear or incomplete, ask follow-up questions + +--- + +## Example Discovery Flow (Context-First Approach) + +**Stage 0 - Context Research (BEFORE asking questions)** + +**Step 1: Auto-Discovery** +``` +Assistant: "Starting context research... + +✓ Auto-discovered from package.json: + - Q9: Node.js 20, React 18 + - Q12: Express, Prisma ORM, PostgreSQL, Jest, Tailwind CSS + +✓ Auto-discovered from Dockerfile: + - Q9: Production runtime: Node.js 20 Alpine +``` + +**Step 2: Request User Materials** +``` +Assistant: "Do you have existing materials I should review before asking questions? +Examples: design documents, technical specifications, requirements docs, legacy system documentation, architectural diagrams, API contracts." + +User: "Yes, here's our design doc and technical spec." +``` + +**Step 3: Extract from Materials** +``` +Assistant: "Reading materials... + +✓ Extracted from design doc: + - Q1: Acceptance criteria defined (user registration, product search <500ms, Stripe checkout) + - Q5: In scope (microservices, PostgreSQL, REST API, JWT auth, Stripe, AWS ECS) + - Q6: Out of scope (no mobile apps, no AI/ML, no cryptocurrency, no GraphQL, no Kubernetes) + - Q7: Integrations: Stripe (payments), SendGrid (emails), AWS S3 (images) + - D1-D6: Full design system documented + +✓ Extracted from technical spec: + - Q3: All functional requirements defined with IDs (15 requirements) + - Q10: Hard constraints (AWS us-east-1, PCI DSS Level 1, no serverless) + - Q11: Microservices architecture + - R1-R2: Technical risks and dependencies documented + +Total extracted: 18/23 questions" +``` + +**Step 4: Research Best Practices** +``` +Assistant: "Researching 2025 best practices... + +✓ Researched via MCP Ref: + - Q12: Verified 2025 versions (Express 5.0, Prisma 6.0, Jest 30.0, Tailwind 4.0) + +✓ Researched via WebSearch: + - Q11: Microservices best practices 2025 (event-driven, API Gateway patterns) + - Q13: Stripe API 2025 best practices (webhook security, idempotency) + +Total gathered in Stage 0: 21/23 questions" +``` + +**Stage 1-2 - Interactive Questions (ONLY remaining)** + +**Batch 1 - Remaining Questions** +``` +Assistant: "✓ Context Research complete! + +Information already gathered (21/23 questions): +- Auto-discovered: Q9, Q12 (from package.json/Dockerfile) +- Extracted from materials: Q1, Q3, Q5, Q6, Q7, Q10, Q11, D1-D6, R1-R2 +- Researched: Q11, Q12, Q13 + +Remaining questions: 2 questions + +Category 1 of 6: Requirements (asking 1 remaining question) +Q2: What is the Minimum Viable Product (MVP) from a technical standpoint? + +Category 2 of 6: Scope (asking 1 remaining question) +Q8: Who are the technical user roles and what are their permissions? + +Please provide your answers." +``` + +--- + +**Key Insight**: Context-first approach reduced interactive questions from 23 → 2 (91% reduction), saving significant user time and ensuring data accuracy from authoritative sources. + +--- + +**Version:** 4.0.0 (MAJOR: Added Priority Order and Stage 0 Context Research) +**Last Updated:** 2025-11-17 +**Changes from v3.0.0:** +- Added "Priority Order: Context First, Questions Last" section at top +- Added Stage 0 (Context Research) before Stage 1-2 +- Updated "Question Metadata" to "3-Stage Discovery" +- Updated Stage descriptions to emphasize REMAINING questions only +- Updated "How to Use This Document" with Stage 0 workflow +- Updated examples to show context-first approach (91% question reduction) +- Clarified that interactive questions are LAST RESORT diff --git a/skills/ln-114-project-docs-creator/references/guides/examples.md b/skills/ln-114-project-docs-creator/references/guides/examples.md new file mode 100644 index 0000000..abdfbdb --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/guides/examples.md @@ -0,0 +1,120 @@ +# Example Usage + +This document provides detailed examples of using the project-documentation-creator skill in different scenarios. + +## Example 1: New Project with Materials + +**User Request**: +``` +"I want to create technical documentation for an existing Node.js e-commerce API" +``` + +**Skill Response (Phase 1)**: +``` +"I'll help you create comprehensive technical documentation. + +1. What type of project is this? → web app, API +2. Is this a new project, rewrite, or enhancement? → existing +``` + +**Skill Response (Phase 2)**: +``` +"Do you have project materials to analyze? (files, diagrams, docs, code)" +User: "Yes, I have package.json, Dockerfile, and docker-compose.yml" + +"Analyzing project materials..." + +✓ Analyzed project materials + +**Detected**: +- Runtime: Node.js 20 LTS +- Framework: Express 4.18 +- Database: PostgreSQL 15 (from docker-compose.yml) +- Cache: Redis 7.2 (from docker-compose.yml) +- ORM: Prisma 5.6 (from package.json) + +**Pre-populated**: Q9 (partial), Q12 (partial) + +"Let's proceed to Stage 1: Understanding Requirements." +``` + +**Skill Response (Phase 3, Stage 1)**: +``` +"Stage 1: Understanding Requirements - Category 1 of 2: Requirements + +Q1: What are the high-level technical acceptance criteria? +Q2: What is the Minimum Viable Product (MVP) from a technical standpoint? +Q3: Are all functional requirements technically defined? + +Please answer these questions." +``` + +**Skill Response (Phase 3, Stage 2)**: +``` +"Stage 1 complete! Research best practices automatically? (Y/N)" +User: "Y" + +"Researching 2025 best practices for your e-commerce API... + +**Researched Technology Stack**: + +**Runtime**: Node.js 20 LTS (detected, confirmed latest) +**Framework**: Express 4.18 → Recommend upgrade to 4.19 (latest stable, security fixes) +**Database**: PostgreSQL 15 → Recommend PostgreSQL 16 (Sep 2023, 5-year support, performance improvements) +**ORM**: Prisma 5.6 → Recommend Prisma 5.7 (latest stable, bug fixes) +**Cache**: Redis 7.2 (confirmed latest stable) + +**Architectural Pattern**: RESTful API with Layered Architecture (Controller → Service → Repository) +Rationale: Matches your current Express setup, clear separation of concerns, testable + +**Additional Libraries**: +- Validation: Zod 3.22 (type-safe schemas) +- Testing: Jest 29 + Supertest 6 (unit + integration) +- Security: helmet 7 + express-rate-limit 7 + +Do you accept these recommendations? (Y/N/Modify)" +``` + +**After All Phases Complete**: +``` +"Technical documentation generation complete! + +**Generated Files**: +- docs/project/requirements.md (15 FR) +- docs/project/architecture.md (with C4 diagrams) +- docs/project/technical_specification.md (includes auto-generated Dockerfile + docker-compose.yml) +- docs/project/adrs/ (5 ADRs: Express, PostgreSQL, Prisma, Redis, REST API) + +**Next Steps**: +1. Review the generated documentation with your technical team +2. Use these documents as input for epic-creator to start creating Epics + +Would you like to review any specific document or make adjustments?" +``` + +## Example 2: New Project without Materials + +**User Request**: +``` +"I want to create technical documentation for a new mobile app project" +``` + +**Skill Response**: +``` +"I'll help you create comprehensive technical documentation. + +1. What type of project is this? → mobile app +2. Is this a new project, rewrite, or enhancement? → new project + +Do you have project materials to analyze? (files, diagrams, docs, code)" +User: "No" + +"Let's begin Stage 1: Understanding Requirements." +``` + +*[Proceeds with fully interactive Q1-Q19 dialog, with automatic research option for Q9, Q11-Q13]* + +--- + +**Version:** 2.0.0 +**Last Updated:** 2025-01-31 diff --git a/skills/ln-114-project-docs-creator/references/guides/template_mappings.md b/skills/ln-114-project-docs-creator/references/guides/template_mappings.md new file mode 100644 index 0000000..140c70e --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/guides/template_mappings.md @@ -0,0 +1,285 @@ +# Template Mappings Reference + +This document details how collected answers from Phase 2 (Core Documents Generation) map to specific sections in the 7 generated documentation templates. + +## Document 1: requirements.md + +**Template File**: `references/templates/requirements_template.md` + +**Structure**: +- Functional Requirements (FR) ONLY organized by feature groups +- NO Non-Functional Requirements (NFR removed per project policy) +- Each requirement includes: ID, Description, Priority (MoSCoW), Acceptance Criteria + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 1.2 Scope | Q1 | High-level technical acceptance criteria | +| Section 2.1 Product Perspective | Q2 | MVP technical scope | +| Section 3 FR by feature groups | Q1, Q2, Q3 | Organize functional requirements by user-facing features | +| Section 5 Constraints | Q10 | Technical and regulatory constraints | + +**Format Example**: +```markdown +### FR-AUTH-001: User Registration +**Priority**: MUST +**Description**: Users can register with email and password +**Acceptance Criteria**: +- Email validation (RFC 5322) +- Password strength requirements (min 12 chars, uppercase, lowercase, number, symbol) +- Confirmation email sent within 5 seconds +``` + +--- + +## Document 2: architecture.md + +**Template File**: `references/templates/architecture_template.md` + +**Structure**: +- 11 sections following arc42 (simplified) + C4 Model +- Includes Mermaid diagrams (C4 Context, Container, Component) +- NO Deployment diagrams (moved to runbook.md) + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 1.1 Requirements Overview | Q1, Q2 | Brief summary linking to requirements.md | +| Section 1.2 Quality Goals | R1 | Top 3-5 quality attributes (performance, security, scalability) | +| Section 2 Constraints | Q10 | Technical, organizational, regulatory constraints | +| Section 3.1 Business Context | Q5, Q6 | External actors and business boundaries | +| Section 3.2 Technical Context | Q7, Q13 | External systems, integrations, interfaces | +| Section 4.1 Technology Decisions | Q9, Q11, Q12 | High-level tech choices with ADR links | +| Section 4.2 Top-Level Decomposition | Q11 | Architecture pattern (layered, microservices, etc.) | +| Section 8 ADRs | Q9, Q11, Q12 | List of all ADR links | +| Section 10 Risks | R2 | Known technical risks and mitigation | + +**Diagram Mappings**: + +| Diagram Type | Generated From | Purpose | +|-------------|---------------|---------| +| C4 Context | Q7 (boundaries), Q13 (integrations) | System + external actors/systems | +| C4 Container | Q11 (architecture), Q9 (database/cache) | Frontend, Backend, Database, Cache, Queue | +| C4 Component | Q11 (pattern), Q12 (frameworks) | API application breakdown (controllers, services, repositories) | + +**Note**: Deployment diagrams removed (now in runbook.md). Quality Goals derived from R1 (risks), NOT from NFR questions. + +--- + +## Document 3: tech_stack.md + +**Template File**: `references/templates/tech_stack_template.md` + +**Structure**: +- 4 sections: Overview, Technology Stack table, Docker configuration, Naming conventions +- NO API endpoints, NO database schema (those in separate docs) + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 2.1 Stack Overview Table | Q9, Q11, Q12 | Detailed version table with rationale and ADR links | +| Section 3.1 Dockerfile | Q9, Q12 (auto-discovered) | Auto-generated multi-stage Dockerfile | +| Section 3.2 docker-compose.yml | Q9, Q12 (auto-discovered) | Auto-generated from package.json + researched versions | +| Section 3.3 docker-compose.test.yml | Q9, Q12 | Test environment configuration | +| Section 4 Naming Conventions | Q8 | File structure, naming patterns | + +**Stack Table Format**: +```markdown +| Layer | Technology | Version | Rationale | ADR | +|-------|-----------|---------|-----------|-----| +| Frontend | Next.js | 14.0 | SSR for SEO, team expertise | ADR-001 | +| Backend | Node.js | 20 LTS | JavaScript fullstack, async I/O | ADR-002 | +| Database | PostgreSQL | 16 | ACID, JSON support, maturity | ADR-003 | +``` + +**Auto-Discovery**: Phase 1.3a extracts Q9 (runtime versions) and Q12 (frameworks) from package.json/Dockerfile before asking user. + +--- + +## Document 4: api_spec.md *(conditional: API/Backend projects only)* + +**Template File**: `references/templates/api_spec_template.md` + +**Structure**: +- 6 sections: Overview, Authentication, API Endpoints, Request/Response schemas, Error Codes, Rate Limiting +- OpenAPI 3.0 compatible structure + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 2 Authentication | Q11, Q12 | JWT/OAuth2/API keys implementation | +| Section 3 API Endpoints | Q1, Q3 (derived) | RESTful endpoints derived from functional requirements | +| Section 5 Error Codes | - | Standard error code taxonomy | +| Section 6 Rate Limiting | Q10 | API rate limits from constraints | + +**Endpoint Table Format**: +```markdown +| Method | Endpoint | Description | Auth Required | Request Body | Response | +|--------|----------|-------------|---------------|--------------|----------| +| POST | /auth/register | Register new user | No | RegisterDTO | UserDTO | +| GET | /products | List products | No | - | ProductDTO[] | +| POST | /orders | Create order | Yes | OrderDTO | OrderDTO | +``` + +**Auto-Generation**: Endpoints derived from FR requirements in Q1, Q3 (e.g., "User Registration" → POST /auth/register). + +--- + +## Document 5: database_schema.md *(conditional: projects with database)* + +**Template File**: `references/templates/database_schema_template.md` + +**Structure**: +- 8 sections: Overview, ER Diagram, Data Dictionary (tables), Indexes, Migrations, Relationships, Constraints, Seed Data +- Mermaid ER diagrams + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 2 ER Diagram | Q3 (derived) | Entities + relationships from functional requirements | +| Section 3 Data Dictionary | Q3 (derived) | Table definitions with columns, types, constraints | +| Section 4 Indexes | Q3, Q9 | Performance optimization indexes | +| Section 5 Migrations | Q9 | Migration strategy (Prisma/TypeORM/Alembic) | +| Section 8 Seed Data | Q3 | Sample data for development | + +**ER Diagram Example**: +```mermaid +erDiagram + USERS ||--o{ ORDERS : places + ORDERS ||--|{ ORDER_ITEMS : contains + PRODUCTS ||--o{ ORDER_ITEMS : "ordered in" + USERS { + uuid id PK + string email UK + string password_hash + timestamp created_at + } +``` + +**Auto-Generation**: Entities derived from Q3 analysis (e.g., "User Registration" → USERS table, "Product Catalog" → PRODUCTS table). + +--- + +## Document 6: design_guidelines.md *(conditional: Frontend/Full-stack projects only)* + +**Template File**: `references/templates/design_guidelines_template.md` + +**Structure**: +- 6 sections: Overview, Core Design Elements (typography, colors, spacing, components), Accessibility, Responsive Design, Brand Assets, Design Tokens +- Based on WCAG 2.1 Level AA standards + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 2.1 Typography | D1 | Font families, sizes, weights, line heights | +| Section 2.2 Color System | D1 | Primary/secondary/semantic colors with hex codes | +| Section 2.3 Spacing System | D1, D3 | 8px base grid, spacing scale (4, 8, 12, 16, 24, 32, 48, 64) | +| Section 2.4 Component Library | D2 | Buttons, Forms, Cards, Modals with Tailwind/MUI classes | +| Section 3 Accessibility | D4 | WCAG compliance, ARIA labels, keyboard navigation | +| Section 4 Responsive Design | D3 | Breakpoints (mobile, tablet, desktop) | +| Section 5 Brand Assets | D5 | Logo usage, imagery guidelines | +| Section 6 Design Tokens | D6 | CSS variables or design system reference | + +**Component Example**: +```markdown +#### Buttons +| Variant | Classes | Usage | +|---------|---------|-------| +| Primary | bg-primary text-white hover:bg-primary-dark px-6 py-3 rounded-lg | Primary CTAs | +| Secondary | bg-secondary text-gray-800 hover:bg-secondary-dark px-6 py-3 rounded-lg | Secondary actions | +``` + +**Skipped for**: Backend-only projects (no frontend). + +--- + +## Document 7: runbook.md *(conditional: Docker-based projects)* + +**Template File**: `references/templates/runbook_template.md` + +**Structure**: +- 9 sections covering ALL environments: local development, testing, production operations +- Includes Docker commands, troubleshooting, SSH access, deployment procedures + +**Key Mappings**: + +| Template Section | Source Questions | Notes | +|-----------------|------------------|-------| +| Section 2.1 Required Tools | O1 (auto-discovered) | Docker, Docker Compose, Node.js, Git versions | +| Section 3 Local Development | O1, Q9 (auto-discovered) | Docker commands extracted from docker-compose.yml | +| Section 4 Testing | O1 | Test commands (unit, integration, e2e) | +| Section 5 Build & Deployment | O2 | Production build and deployment procedures | +| Section 6 Production Operations | O2, O3 | SSH access, health checks, monitoring, logs | +| Section 7 Troubleshooting | O3 | Common issues and resolutions | +| Appendix A | O1 (auto-discovered) | Environment variables from .env.example | + +**Docker Commands Example**: +```bash +# Start all services +docker compose up -d + +# Rebuild after code changes +docker compose down +docker compose build --no-cache app +docker compose up -d + +# View logs +docker compose logs -f app +``` + +**Auto-Discovery**: Docker commands, environment variables, and service names extracted from Dockerfile and docker-compose.yml in Phase 1.3a. + +--- + +## Template Placeholder Format + +All templates use explicit placeholder mapping with comments for traceability: + +```markdown +**Technology Stack:** {{TECHNOLOGY_STACK}} + + +**Architecture Pattern:** {{ARCHITECTURE_PATTERN}} + + +**Color System:** {{COLOR_SYSTEM}} + + +**Docker Commands:** {{DOCKER_COMMANDS}} + +``` + +This format allows clear traceability from questions to documentation sections. Auto-discovery annotations indicate when data is extracted automatically in Phase 1.3a. + +--- + +## Appendix: ADRs (Auto-Generated) + +**Note**: ADRs are still auto-generated as part of the documentation suite, but are NOT one of the 7 main documents. + +**Template File**: `references/templates/adr_template.md` + +**Generated ADRs** (3-5 per project): + +| ADR | Title | Source Questions | When Generated | +|-----|-------|------------------|---------------| +| ADR-001 | Frontend Framework Choice | Q11, Q12 | If frontend framework specified | +| ADR-002 | Backend Framework Choice | Q11, Q12 | Always (every project has backend) | +| ADR-003 | Database Choice | Q9 | If database specified | +| ADR-004 | Additional Technology 1 | Q12 | If significant library chosen (ORM, cache, queue) | +| ADR-005 | Additional Technology 2 | Q12 | If multiple significant choices made | + +**Format**: Michael Nygard's ADR format (Context, Decision, Rationale, Consequences, Alternatives Considered) + +**Location**: `docs/reference/adrs/adr-NNN-*.md` + +--- + +**Version:** 2.0.0 (BREAKING: Updated for 7-document structure. Added tech_stack, api_spec, database_schema, design_guidelines, runbook mappings. Removed NFR mappings. Updated question IDs: Q1-Q13, D1-D6, O1-O3, R1-R2.) +**Last Updated:** 2025-11-16 diff --git a/skills/ln-114-project-docs-creator/references/guides/troubleshooting.md b/skills/ln-114-project-docs-creator/references/guides/troubleshooting.md new file mode 100644 index 0000000..85d4d21 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/guides/troubleshooting.md @@ -0,0 +1,41 @@ +# Troubleshooting Guide + +This document provides solutions to common issues when using the x-docs-creator skill. + +## Issue 1: User Doesn't Know Answers + +**Problem**: User doesn't know answers to some technical questions during Phase 3 discovery. + +**Solution**: +- Mark questions as "TBD" and flag for follow-up +- Generate documents with placeholders (e.g., `{{TODO: Define performance requirements}}`) +- Skill can be re-run later to update documentation once answers are available +- Documents remain valid with TBD placeholders for initial planning + +## Issue 2: Project Too Small + +**Problem**: Project is very small (1-2 person team, simple app) and 19 questions seem excessive. + +**Solution**: +- Skip optional questions that don't apply to small projects +- Generate minimal viable technical documentation: + - Requirements document (simplified FR only - critical functional requirements) + - Simplified Architecture (basic tech stack + deployment diagram) + - Skip detailed technical specifications and ADRs if not needed +- Focus on Q1-Q8 (requirements + scope) as minimum viable documentation + +## Issue 3: Auto-Research Returns Outdated Technologies + +**Problem**: Phase 3 Stage 2 auto-research recommends outdated or deprecated technologies. + +**Solution**: +- **Verify Research Date**: Skill uses current date (2025) for research +- **Check MCP Ref Results**: Review specific library documentation returned +- **Manually Verify**: Cross-check recommendations with official docs +- **Override if Needed**: Select "Modify" option to override recommendations +- **Report Issue**: If persistent, check skill version and update + +--- + +**Version:** 2.0.0 +**Last Updated:** 2025-01-31 diff --git a/skills/ln-114-project-docs-creator/references/questions.md b/skills/ln-114-project-docs-creator/references/questions.md new file mode 100644 index 0000000..141d2c1 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/questions.md @@ -0,0 +1,750 @@ +# Project Documentation Questions + +**Purpose:** Define what each section of project documentation should answer. + +**Format:** Question → Expected Answer → Validation Heuristics → Auto-Discovery → MCP Ref Hints + +--- + +## Table of Contents + +| Document | Questions | Auto-Discovery | Priority | Line | +|----------|-----------|----------------|----------|------| +| [requirements.md](#docsprojectrequirementsmd) | 1 | Low | Critical | L30 | +| [architecture.md](#docsprojectarchitecturemd) | 11 | High | Critical | L92 | +| [tech_stack.md](#docsprojecttechstackmd) | 4 | High | High | L394 | +| [api_spec.md](#docsprojectapispecmd) | 2 | Medium | High | L495 | +| [database_schema.md](#docsprojectdatabaseschemamd) | 2 | High | High | L560 | +| [design_guidelines.md](#docsprojectdesignguidelinesmd) | 3 | Low | Medium | L625 | +| [runbook.md](#docsprojectrunbookmd) | 3 | High | Critical | L715 | + +**Priority Legend:** +- **Critical:** Must answer all questions (requirements, architecture, runbook) +- **High:** Strongly recommended (tech_stack, api_spec, database_schema) +- **Medium:** Optional for some project types (design_guidelines - frontend only) + +**Auto-Discovery Legend:** +- **None:** No auto-discovery needed (use template as-is) +- **Low:** 1-2 questions need auto-discovery +- **Medium:** 50% questions need auto-discovery +- **High:** Most/all questions need auto-discovery + +--- + + +## docs/project/requirements.md + +**File:** docs/project/requirements.md (functional requirements ONLY) +**Target Sections:** Functional Requirements + +**Rules for this document:** +- ISO/IEC/IEEE 29148:2018 compliant +- FR-XXX-NNN identifiers for all requirements +- MoSCoW prioritization (MUST/SHOULD/COULD/WON'T) +- User stories or acceptance criteria format + +--- + + +### Question 1: What functionality must the system provide? + +**Expected Answer:** Numbered list of functional requirements with FR-XXX-NNN identifiers, MoSCoW priorities, user stories/acceptance criteria +**Target Section:** ## Functional Requirements + +**Validation Heuristics:** +- ✅ Has FR-XXX identifiers (e.g., FR-001, FR-USR-001) +- ✅ Has MoSCoW labels (MUST/SHOULD/COULD/WON'T) +- ✅ Length > 100 words +- ✅ Has numbered list or table + +**Auto-Discovery:** +- Check: package.json → "description" for feature clues +- Check: README.md for feature mentions +- Check: existing docs for use case descriptions + +**MCP Ref Hints:** +- Research: "functional requirements best practices" +- Research: "MoSCoW prioritization method" + + + + +--- + + +## docs/project/architecture.md + +**File:** docs/project/architecture.md (arc42 framework with C4 Model) +**Target Sections:** 11 sections (Introduction and Goals → Glossary) + +**Rules for this document:** +- ISO/IEC/IEEE 42010:2022 compliant +- arc42 framework structure (11 sections) +- C4 Model diagrams (Context, Container, Component) +- Mermaid syntax for all diagrams + +--- + + +### Question 3: What are the key quality goals and stakeholders? + +**Expected Answer:** Requirements overview summary, 5 quality goals with metrics (Performance, Security, Scalability, Reliability, Maintainability), stakeholders table with roles +**Target Section:** ## 1. Introduction and Goals + +**Validation Heuristics:** +- ✅ Has subsections 1.1, 1.2, 1.3 +- ✅ Quality goals have measurable metrics +- ✅ Stakeholders table has roles and expectations +- ✅ References requirements.md + +**Auto-Discovery:** +- Check: architecture.md → Section 1.2 Quality Goals (derived from risks R1) +- Check: package.json → "author" for stakeholder hints + +**MCP Ref Hints:** +- Research: "arc42 quality goals" +- Research: "ISO 25010 quality attributes" + + +--- + + +### Question 4: What technical and organizational constraints exist? + +**Expected Answer:** Technical constraints (languages, databases, cloud providers), organizational constraints (team size, compliance), conventions (code style, testing standards) +**Target Section:** ## 2. Constraints + +**Validation Heuristics:** +- ✅ Has subsections 2.1 (Technical), 2.2 (Organizational), 2.3 (Conventions) +- ✅ Mentions specific technologies +- ✅ Lists compliance requirements (GDPR, HIPAA, etc.) + +**Auto-Discovery:** +- Check: package.json → "dependencies" for tech stack +- Check: .eslintrc, .prettierrc for code style conventions +- Check: tsconfig.json, jest.config.js for conventions + +**MCP Ref Hints:** +- Research: "architecture constraints examples" + + +--- + + +### Question 5: What are the system boundaries and external interfaces? + +**Expected Answer:** Business context (actors, external systems), technical context (protocols, data formats), C4 Context diagram (Mermaid) +**Target Section:** ## 3. Context and Scope + +**Validation Heuristics:** +- ✅ Has subsections 3.1 (Business Context), 3.2 (Technical Context) +- ✅ Has Mermaid code block with C4 Context diagram +- ✅ Lists external systems and protocols + +**Auto-Discovery:** +- Check: package.json → "dependencies" for external service clients (stripe, twilio, aws-sdk) +- Check: .env.example for API_URL, DATABASE_URL (external systems) + +**MCP Ref Hints:** +- Research: "C4 model context diagram examples" +- Research: "system context best practices" + + +--- + + +### Question 6: What are the top-level architectural decisions? + +**Expected Answer:** Technology decisions table (Frontend, Backend, Database with rationale and ADR links), top-level decomposition approach (Layered/Microservices/Modular), approach to quality goals +**Target Section:** ## 4. Solution Strategy + +**Validation Heuristics:** +- ✅ Has subsections 4.1 (Technology Decisions), 4.2 (Top-level Decomposition), 4.3 (Quality Goals Approach) +- ✅ Technology table references ADRs +- ✅ Explains architecture pattern choice + +**Auto-Discovery:** +- Check: package.json → "dependencies" for frontend/backend frameworks +- Check: src/ directory structure: + - controllers/, services/, repositories/ → Layered architecture + - modules/, features/ → Modular architecture + - pages/, components/ → Frontend structure + +**MCP Ref Hints:** +- Research: "layered architecture vs microservices" +- Research: "architecture patterns comparison 2024" + + +--- + + +### Question 7: How is the system decomposed into components? + +**Expected Answer:** C4 diagrams (Level 1 System Context, Level 2 Container, Level 3 Component), key components table, infrastructure layer components +**Target Section:** ## 5. Building Block View + +**Validation Heuristics:** +- ✅ Has subsections 5.1 (Level 1), 5.2 (Level 2), 5.3 (Level 3) +- ✅ Has 3 Mermaid C4 diagrams +- ✅ Has components table with responsibilities + +**Auto-Discovery:** +- Scan: src/ directory for folders (controllers, services, repositories, components) +- Check: package.json → "main" for entry point +- Count: number of controllers, services, components + +**MCP Ref Hints:** +- Research: "C4 model component diagram" +- Research: "software architecture decomposition patterns" + + +--- + + +### Question 8: What are the critical runtime scenarios? + +**Expected Answer:** 3-5 key scenarios with sequence diagrams (User Registration, Product Purchase, API Request Flow, etc.) +**Target Section:** ## 6. Runtime View + +**Validation Heuristics:** +- ✅ Has subsections 6.1, 6.2, 6.3 (at least 3 scenarios) +- ✅ Each subsection has Mermaid sequence diagram +- ✅ Scenarios align with functional requirements + +**Auto-Discovery:** +- Check: requirements.md for use cases/user stories +- Check: api_spec.md for endpoint flows + +**MCP Ref Hints:** +- Research: "sequence diagram best practices" +- Research: "runtime view arc42 examples" + + +--- + + +### Question 9: What concepts apply across the system? + +**Expected Answer:** Crosscutting concepts for Security (Auth, Authorization, Encryption), Error Handling, Configuration Management, Data Access Pattern +**Target Section:** ## 7. Crosscutting Concepts + +**Validation Heuristics:** +- ✅ Has subsections 7.1 (Security), 7.2 (Error Handling), 7.3 (Configuration), 7.4 (Data Access) +- ✅ Each subsection > 50 words +- ✅ References specific libraries/patterns + +**Auto-Discovery:** +- Check: package.json → "dependencies" for auth libraries (passport, jsonwebtoken, bcrypt) +- Check: .env.example for configuration patterns +- Check: src/models or src/repositories for data access pattern + +**MCP Ref Hints:** +- Research: "security architecture best practices" +- Research: "repository pattern vs active record" +- Research: "error handling patterns Node.js/Python/Go" + + +--- + + +### Question 10: What are the key architecture decisions and their rationale? + +**Expected Answer:** List of ADRs with links to docs/reference/adrs/, critical ADRs summary (top 3-5 decisions) +**Target Section:** ## 8. Architecture Decisions (ADRs) + +**Validation Heuristics:** +- ✅ Has placeholder {{ADR_LIST}} or actual ADR links +- ✅ Has "Critical ADRs Summary" subsection +- ✅ Links to docs/reference/adrs/ directory + +**Auto-Discovery:** +- Scan: docs/reference/adrs/ for *.md files +- Read: ADR titles from filenames or file headers + +**MCP Ref Hints:** +- N/A (ADRs are project-specific) + + +--- + + +### Question 11: What are the quality scenarios and metrics? + +**Expected Answer:** Quality tree (ISO 25010 hierarchy), quality scenarios table with testable criteria (QS-1, QS-2, ...) +**Target Section:** ## 9. Quality Requirements + +**Validation Heuristics:** +- ✅ Has subsections 9.1 (Quality Tree), 9.2 (Quality Scenarios) +- ✅ Quality scenarios have testable criteria +- ✅ References ISO 25010 quality model + +**Auto-Discovery:** +- Check: architecture.md → Section 1.2 Quality Goals + +**MCP Ref Hints:** +- Research: "ISO 25010 quality scenarios" +- Research: "quality attribute workshop methods" + + +--- + + +### Question 12: What are the known risks and technical debt? + +**Expected Answer:** Technical risks list with likelihood/impact, technical debt table (item, impact, plan, timeline), mitigation strategies +**Target Section:** ## 10. Risks and Technical Debt + +**Validation Heuristics:** +- ✅ Has subsections 10.1 (Risks), 10.2 (Technical Debt), 10.3 (Mitigation) +- ✅ Technical debt table has timeline +- ✅ Risks have likelihood and impact ratings + +**Auto-Discovery:** +- Check: package.json → "dependencies" for outdated/EOL versions (npm outdated) +- Scan: codebase for TODO/FIXME comments +- Check: .github/dependabot.yml for security alerts + +**MCP Ref Hints:** +- Research: "technical debt management best practices" +- Research: "architecture risk assessment methods" + + +--- + + +### Question 13: What domain terms need definition? + +**Expected Answer:** Table of terms and definitions, standard C4/architecture terms (Container, Component, SSR, RBAC, JWT) +**Target Section:** ## 11. Glossary + +**Validation Heuristics:** +- ✅ Has table with Term | Definition columns +- ✅ Contains standard C4/architecture terms +- ✅ Includes project-specific domain terms + +**Auto-Discovery:** +- Scan: all docs for domain-specific terms (business terminology) +- Extract: technical acronyms from code (API, SSR, RBAC, JWT) + +**MCP Ref Hints:** +- Research: "C4 model glossary standard terms" + + + + +--- + + +## docs/project/tech_stack.md + +**File:** docs/project/tech_stack.md (technology stack with versions and rationale) +**Target Sections:** Frontend Technologies, Backend Technologies, Database, Additional Technologies + +**Rules for this document:** +- Technology table with Name, Version, Rationale, ADR Link +- Docker configuration (Dockerfile + docker-compose.yml) +- Version pinning and upgrade strategy + +--- + + +### Question 14: What frontend technologies are used and why? + +**Expected Answer:** Framework name (React, Vue, Angular), version, rationale (team expertise, performance, ecosystem), key libraries +**Target Section:** ## Frontend Technologies + +**Validation Heuristics:** +- ✅ Mentions framework name (React, Vue, Angular, Svelte) +- ✅ Has version number +- ✅ Has "Rationale" or "Why" explanation +- ✅ Lists key libraries (state management, routing, UI) + +**Auto-Discovery:** +- Check: package.json → "dependencies" for frontend frameworks (react, vue, @angular/core, svelte) +- Extract: version numbers from package.json +- Check: package.json → react-router-dom, redux, vuex, pinia, @ngrx/store + +**MCP Ref Hints:** +- Research: "[framework] latest version features 2024" +- Research: "[framework] best practices" + + +--- + + +### Question 15: What backend technologies are used and why? + +**Expected Answer:** Runtime (Node.js, Python, Go, Java), framework (Express, FastAPI, Gin, Spring Boot), version, rationale +**Target Section:** ## Backend Technologies + +**Validation Heuristics:** +- ✅ Mentions runtime + framework +- ✅ Has version numbers +- ✅ Has rationale explanation + +**Auto-Discovery:** +- Check: package.json → "dependencies" (express, fastify, koa, nestjs) +- Check: requirements.txt, pyproject.toml (fastapi, django, flask) +- Check: go.mod (gin, echo, fiber) +- Check: pom.xml, build.gradle (spring-boot) + +**MCP Ref Hints:** +- Research: "[runtime] [framework] performance comparison 2024" + + +--- + + +### Question 16: What database technologies are used and why? + +**Expected Answer:** Database type (PostgreSQL, MongoDB, MySQL), version, rationale (ACID, JSON support, scalability) +**Target Section:** ## Database + +**Validation Heuristics:** +- ✅ Mentions database name +- ✅ Has version number +- ✅ Has rationale (ACID, performance, features) + +**Auto-Discovery:** +- Check: package.json → "dependencies" (pg, mongoose, mysql2, sqlite3) +- Check: docker-compose.yml for database services (postgres, mongo, mysql, redis) +- Check: requirements.txt (psycopg2, pymongo, mysql-connector) + +**MCP Ref Hints:** +- Research: "[database] version features" +- Research: "PostgreSQL vs MongoDB comparison" + + +--- + + +### Question 17: What other key technologies are used? + +**Expected Answer:** Caching (Redis, Memcached), message queue (RabbitMQ, Kafka), search (Elasticsearch, Algolia), file storage (S3, local) +**Target Section:** ## Additional Technologies + +**Validation Heuristics:** +- ✅ Lists categories with technologies +- ✅ Each technology has version and rationale + +**Auto-Discovery:** +- Check: package.json → "dependencies" for all libraries (redis, ioredis, amqplib, kafkajs, @elastic/elasticsearch) +- Check: docker-compose.yml for additional services (redis, rabbitmq, elasticsearch) + +**MCP Ref Hints:** +- Research: "redis vs memcached comparison" +- Research: "rabbitmq vs kafka use cases" + + + + +--- + + +## docs/project/api_spec.md + +**File:** docs/project/api_spec.md (API specification - Backend/Full-stack only) +**Target Sections:** API Overview, Endpoints + +**Rules for this document:** +- OpenAPI 3.0 compatible format +- RESTful/GraphQL/gRPC patterns +- Authentication and error codes documented + +**Note:** This document is conditional - only validate for Backend/Full-stack projects + +--- + + +### Question 18: What is the API architecture and authentication? + +**Expected Answer:** API type (RESTful, GraphQL, gRPC), base URL, versioning strategy (URL/header), authentication (JWT, OAuth2, API keys) +**Target Section:** ## API Overview + +**Validation Heuristics:** +- ✅ Mentions API type (REST, GraphQL, gRPC) +- ✅ Has base URL or pattern +- ✅ Describes auth method (JWT, OAuth2, API keys) +- ✅ Explains versioning strategy + +**Auto-Discovery:** +- Check: package.json → "dependencies" (express, @apollo/server, @grpc/grpc-js) +- Scan: src/routes/ or src/controllers/ for endpoint patterns +- Check: .env.example for API_BASE_URL, JWT_SECRET + +**MCP Ref Hints:** +- Research: "REST API design best practices" +- Research: "API authentication methods comparison" + + +--- + + +### Question 19: What are the available API endpoints? + +**Expected Answer:** Table of endpoints (Method, Path, Description), request/response examples, error codes +**Target Section:** ## Endpoints + +**Validation Heuristics:** +- ✅ Has endpoint table with Method | Path | Description +- ✅ Has request/response examples +- ✅ Documents error codes (400, 401, 403, 404, 500) + +**Auto-Discovery:** +- Scan: src/routes/*.js, src/routes/*.ts for route definitions +- Check: OpenAPI/Swagger spec file if exists (openapi.yaml, swagger.json) +- Extract: HTTP methods (GET, POST, PUT, DELETE, PATCH) + +**MCP Ref Hints:** +- Research: "OpenAPI specification examples" +- Research: "REST API endpoint documentation" + + + + +--- + + +## docs/project/database_schema.md + +**File:** docs/project/database_schema.md (database schema - conditional) +**Target Sections:** Schema Overview, Tables/Collections + +**Rules for this document:** +- ER diagrams in Mermaid syntax +- Data dictionary with all tables/collections +- Relationships and constraints documented + +**Note:** This document is conditional - only validate if database detected in dependencies + +--- + + +### Question 20: What is the database structure? + +**Expected Answer:** Database type (SQL/NoSQL), schema diagram (Mermaid ERD), table/collection list +**Target Section:** ## Schema Overview + +**Validation Heuristics:** +- ✅ Has Mermaid ERD diagram +- ✅ Lists all tables/collections +- ✅ Shows relationships between tables + +**Auto-Discovery:** +- Check: migrations/ or schema/ directory for table definitions +- Check: src/models/ for entity definitions (Sequelize, TypeORM, Prisma, Mongoose) +- Scan: migration files for CREATE TABLE statements + +**MCP Ref Hints:** +- Research: "database ERD diagram examples" +- Research: "database schema best practices" + + +--- + + +### Question 21: What are the table structures and relationships? + +**Expected Answer:** For each table: columns, types, constraints, relationships (foreign keys, references) +**Target Section:** ## Tables/Collections + +**Validation Heuristics:** +- ✅ Has table definitions with columns and types +- ✅ Describes relationships (1:1, 1:N, N:M) +- ✅ Documents constraints (PRIMARY KEY, FOREIGN KEY, UNIQUE, NOT NULL) + +**Auto-Discovery:** +- Read: migration files for detailed column definitions +- Read: model files (models/*.js, models/*.ts) for schema definitions +- Extract: foreign key relationships + +**MCP Ref Hints:** +- Research: "database normalization best practices" +- Research: "SQL foreign key relationships" + + + + +--- + + +## docs/project/design_guidelines.md + +**File:** docs/project/design_guidelines.md (UI/UX design system - Frontend only) +**Target Sections:** Design System, Typography, Colors + +**Rules for this document:** +- WCAG 2.1 Level AA compliant +- Design system or component library documented +- Accessibility guidelines included + +**Note:** This document is conditional - only validate for Frontend/Full-stack projects + +--- + + +### Question 22: What is the design system or component library? + +**Expected Answer:** Design system name (Material-UI, Ant Design, custom), key components, customization approach +**Target Section:** ## Design System + +**Validation Heuristics:** +- ✅ Mentions design system name or "custom design system" +- ✅ Lists key components (Button, Input, Card, Modal, etc.) +- ✅ Explains customization/theming approach + +**Auto-Discovery:** +- Check: package.json → "dependencies" (@mui/material, antd, chakra-ui, @headlessui/react) +- Scan: src/components/ for component library usage + +**MCP Ref Hints:** +- Research: "[design system] customization guide" +- Research: "design system best practices 2024" + + +--- + + +### Question 23: What fonts and text styles are used? + +**Expected Answer:** Font families (primary, secondary), font sizes (headings, body, small), font weights +**Target Section:** ## Typography + +**Validation Heuristics:** +- ✅ Lists font families +- ✅ Has size/weight specifications +- ✅ Shows typography scale (h1-h6, body, small) + +**Auto-Discovery:** +- Check: src/styles/ or CSS files for font definitions +- Check: package.json → "dependencies" for font libraries (@fontsource/*, next/font) +- Check: tailwind.config.js for fontFamily settings + +**MCP Ref Hints:** +- Research: "typography scale best practices" +- Research: "web font pairing guide" + + +--- + + +### Question 24: What is the color palette? + +**Expected Answer:** Primary, secondary, accent colors (hex codes), neutral colors (grays), semantic colors (success, error, warning, info) +**Target Section:** ## Colors + +**Validation Heuristics:** +- ✅ Lists colors with hex codes +- ✅ Has semantic color categories +- ✅ Shows accessibility contrast ratios + +**Auto-Discovery:** +- Check: CSS variables or theme files (theme.js, theme.ts) +- Check: tailwind.config.js for color palette +- Scan: src/styles/ for color definitions + +**MCP Ref Hints:** +- Research: "accessible color palette design" +- Research: "WCAG color contrast requirements" + + + + +--- + + +## docs/project/runbook.md + +**File:** docs/project/runbook.md (operations guide) +**Target Sections:** Local Development Setup, Deployment, Troubleshooting + +**Rules for this document:** +- Step-by-step setup instructions +- Environment variables documented +- Common issues and solutions + +--- + + +### Question 25: How do I set up the project locally? + +**Expected Answer:** Prerequisites (Node.js version, Docker, etc.), installation steps (npm install, env setup), run commands (npm start, docker-compose up) +**Target Section:** ## Local Development Setup + +**Validation Heuristics:** +- ✅ Lists prerequisites with versions +- ✅ Has numbered installation steps +- ✅ Has run commands for development + +**Auto-Discovery:** +- Check: package.json → "engines" for version requirements (node, npm) +- Check: package.json → "scripts" for run commands (dev, start, build) +- Check: README.md for setup instructions +- Check: Dockerfile for runtime requirements + +**MCP Ref Hints:** +- N/A (project-specific setup) + + +--- + + +### Question 26: How is the application deployed? + +**Expected Answer:** Deployment target (AWS, Vercel, Heroku, Docker), build commands, environment variables, deployment steps +**Target Section:** ## Deployment + +**Validation Heuristics:** +- ✅ Mentions deployment platform +- ✅ Has build commands +- ✅ Lists required env vars +- ✅ Shows deployment steps or CI/CD pipeline + +**Auto-Discovery:** +- Check: package.json → "scripts" → "build" +- Check: .env.example for required env vars +- Check: Dockerfile, vercel.json, .platform.app.yaml for deployment config +- Check: .github/workflows/ for CI/CD + +**MCP Ref Hints:** +- Research: "[platform] deployment best practices" +- Research: "CI/CD pipeline setup for [platform]" + + +--- + + +### Question 27: How do I troubleshoot common issues? + +**Expected Answer:** Common errors with solutions, debugging techniques, log locations +**Target Section:** ## Troubleshooting + +**Validation Heuristics:** +- ✅ Lists common errors and solutions +- ✅ Mentions debugging techniques +- ✅ Shows log locations or commands + +**Auto-Discovery:** +- Check: package.json → "dependencies" for logging libraries (winston, pino, bunyan) +- Scan: README.md for troubleshooting section +- Check: .gitignore for log file patterns (*.log, logs/) + +**MCP Ref Hints:** +- Research: "[framework] common issues troubleshooting" +- Research: "debugging best practices for [runtime]" + + + + +--- + +**Overall Validation Rules:** +- ✅ All 7 documents exist (3 always required + 4 conditional) +- ✅ Each document has SCOPE tags +- ✅ Each document has Maintenance section +- ✅ Total questions answered: 27/27 for full-stack projects, 22/27 for backend-only, 24/27 for frontend-only + +--- + +**Version:** 1.0.0 +**Last Updated:** 2025-11-18 \ No newline at end of file diff --git a/skills/ln-114-project-docs-creator/references/templates/api_spec_template.md b/skills/ln-114-project-docs-creator/references/templates/api_spec_template.md new file mode 100644 index 0000000..bff149d --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/api_spec_template.md @@ -0,0 +1,373 @@ +# API Specification: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} +**OpenAPI Version:** 3.0.3 + + + + +--- + +## 1. API Overview + +### 1.1 Base URL +{{BASE_URL}} + + +### 1.2 API Design Principles +{{API_DESIGN_PRINCIPLES}} + + +### 1.3 API Versioning +{{API_VERSIONING}} + + +--- + +## 2. Authentication & Authorization + +### 2.1 Authentication Methods + +**Supported Methods:** +{{AUTH_METHODS}} + + +**JWT Token Format:** +```json +{ + "header": { + "alg": "HS256", + "typ": "JWT" + }, + "payload": { + "sub": "user_id", + "role": "admin", + "exp": 1234567890 + } +} +``` + +**Token Expiration:** +{{TOKEN_EXPIRATION}} + + +### 2.2 Authorization (RBAC) + +**Roles:** +{{RBAC_ROLES}} + + +--- + +## 3. API Endpoints + +### 3.1 Authentication Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| POST | `/auth/register` | Register new user | No | +| POST | `/auth/login` | Login (email/password) | No | +| POST | `/auth/refresh` | Refresh access token | Yes (Refresh token) | +| POST | `/auth/logout` | Logout (invalidate tokens) | Yes | +| GET | `/auth/me` | Get current user info | Yes | + +**Example: POST /auth/login** + +Request: +```json +{ + "email": "user@example.com", + "password": "secure_password" +} +``` + +Response (200 OK): +```json +{ + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "expiresIn": 3600, + "user": { + "id": "uuid", + "email": "user@example.com", + "role": "editor" + } +} +``` + +--- + +### 3.2 User Management Endpoints + +| Method | Endpoint | Description | Auth Required | Roles | +|--------|----------|-------------|---------------|-------| +| GET | `/users` | List all users (paginated) | Yes | Admin | +| GET | `/users/:id` | Get user by ID | Yes | Admin, self | +| PUT | `/users/:id` | Update user | Yes | Admin, self | +| DELETE | `/users/:id` | Delete user | Yes | Admin | +| PATCH | `/users/:id/password` | Change password | Yes | Admin, self | + +**Example: GET /users?page=1&limit=20** + +Response (200 OK): +```json +{ + "data": [ + { + "id": "uuid", + "email": "user@example.com", + "role": "editor", + "createdAt": "2024-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 150, + "totalPages": 8 + } +} +``` + +--- + +### 3.3 {{RESOURCE_1}} Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| GET | `/{{resource}}` | List {{resource}} | Yes | +| GET | `/{{resource}}/:id` | Get {{resource}} by ID | Yes | +| POST | `/{{resource}}` | Create {{resource}} | Yes | +| PUT | `/{{resource}}/:id` | Update {{resource}} | Yes | +| DELETE | `/{{resource}}/:id` | Delete {{resource}} | Yes | + + + +--- + +### 3.4 {{RESOURCE_2}} Endpoints + +{{RESOURCE_2_ENDPOINTS}} + + +--- + +## 4. Request & Response Formats + +### 4.1 Common Query Parameters + +| Parameter | Type | Description | Example | +|-----------|------|-------------|---------| +| `page` | integer | Page number (1-based) | `?page=2` | +| `limit` | integer | Items per page (max 100) | `?limit=50` | +| `sort` | string | Sort field (+asc, -desc) | `?sort=-createdAt` | +| `filter` | string | Filter expression | `?filter=status:active` | +| `search` | string | Search query | `?search=keyword` | + +### 4.2 Standard Response Structure + +**Success Response:** +```json +{ + "data": { /* resource data */ }, + "meta": { /* metadata, pagination */ } +} +``` + +**Error Response:** +```json +{ + "error": { + "code": "ERROR_CODE", + "message": "Human-readable error message", + "details": [ /* validation errors, if applicable */ ] + } +} +``` + +--- + +## 5. Error Codes + +### 5.1 HTTP Status Codes + +| Status | Meaning | When Used | +|--------|---------|-----------| +| 200 | OK | Successful GET, PUT, PATCH | +| 201 | Created | Successful POST | +| 204 | No Content | Successful DELETE | +| 400 | Bad Request | Invalid request format, validation errors | +| 401 | Unauthorized | Missing or invalid authentication token | +| 403 | Forbidden | Authenticated but insufficient permissions | +| 404 | Not Found | Resource not found | +| 409 | Conflict | Duplicate resource (email already exists) | +| 422 | Unprocessable Entity | Validation errors | +| 429 | Too Many Requests | Rate limit exceeded | +| 500 | Internal Server Error | Unexpected server error | + +### 5.2 Custom Error Codes + +| Code | HTTP Status | Description | Example | +|------|-------------|-------------|---------| +| `AUTH_INVALID_CREDENTIALS` | 401 | Invalid email/password | Login failed | +| `AUTH_TOKEN_EXPIRED` | 401 | JWT token expired | Token needs refresh | +| `AUTH_INSUFFICIENT_PERMISSIONS` | 403 | User lacks required role | Admin-only action | +| `VALIDATION_FAILED` | 422 | Input validation failed | Missing required field | +| `RESOURCE_NOT_FOUND` | 404 | Requested resource not found | User ID not found | +| `RESOURCE_CONFLICT` | 409 | Resource already exists | Email already registered | +| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | 100 req/min limit hit | + +**Example Error Response:** +```json +{ + "error": { + "code": "VALIDATION_FAILED", + "message": "Validation failed for request body", + "details": [ + { + "field": "email", + "message": "Invalid email format" + }, + { + "field": "password", + "message": "Password must be at least 8 characters" + } + ] + } +} +``` + +--- + +## 6. Rate Limiting + +**Limits:** +{{RATE_LIMITS}} + + +**Rate Limit Headers:** +``` +X-RateLimit-Limit: 100 +X-RateLimit-Remaining: 75 +X-RateLimit-Reset: 1640000000 +``` + +--- + +## 7. Pagination + +**Request:** +``` +GET /users?page=2&limit=20 +``` + +**Response:** +```json +{ + "data": [ /* 20 users */ ], + "pagination": { + "page": 2, + "limit": 20, + "total": 150, + "totalPages": 8, + "hasNext": true, + "hasPrev": true + }, + "links": { + "self": "/users?page=2&limit=20", + "first": "/users?page=1&limit=20", + "prev": "/users?page=1&limit=20", + "next": "/users?page=3&limit=20", + "last": "/users?page=8&limit=20" + } +} +``` + +--- + +## 8. OpenAPI Specification + +**OpenAPI Documentation:** +{{OPENAPI_LINK}} + + +**Example OpenAPI Snippet (users endpoint):** +```yaml +paths: + /users: + get: + summary: List all users + tags: [Users] + security: + - bearerAuth: [] + parameters: + - name: page + in: query + schema: + type: integer + default: 1 + - name: limit + in: query + schema: + type: integer + default: 20 + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/User' + pagination: + $ref: '#/components/schemas/Pagination' +``` + +--- + +## 9. Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New API endpoints added +- Authentication/authorization changes +- Error code modifications +- Rate limiting adjustments +- API versioning (major/minor releases) + +**Verification:** +- [ ] All endpoints documented with methods/paths/params/responses +- [ ] Authentication requirements specified for each endpoint +- [ ] Error codes match implementation +- [ ] OpenAPI specification up to date +- [ ] Rate limits tested and validated + +--- + +**Version:** 1.0.0 +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-114-project-docs-creator/references/templates/architecture_template.md b/skills/ln-114-project-docs-creator/references/templates/architecture_template.md new file mode 100644 index 0000000..9129462 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/architecture_template.md @@ -0,0 +1,271 @@ +# Software Architecture Document: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} +**Architecture Framework:** arc42 (simplified) +**Standard Compliance:** ISO/IEC/IEEE 42010:2022 + + + + +--- + +## 1. Introduction and Goals + +### 1.1 Requirements Overview +{{REQUIREMENTS_OVERVIEW}} + + +### 1.2 Quality Goals +{{QUALITY_GOALS}} + + +### 1.3 Stakeholders +{{STAKEHOLDERS_SUMMARY}} + + +--- + +## 2. Constraints + +### 2.1 Technical Constraints +{{TECHNICAL_CONSTRAINTS}} + + +### 2.2 Organizational Constraints +{{ORGANIZATIONAL_CONSTRAINTS}} + + +### 2.3 Conventions +{{CONVENTIONS}} + + +--- + +## 3. Context and Scope + +### 3.1 Business Context +{{BUSINESS_CONTEXT}} + + +**Business Context Diagram:** +```mermaid +{{BUSINESS_CONTEXT_DIAGRAM}} +``` + +**External Interfaces:** +{{EXTERNAL_INTERFACES}} + + +### 3.2 Technical Context +{{TECHNICAL_CONTEXT}} + + +**Technical Context Diagram:** +```mermaid +{{TECHNICAL_CONTEXT_DIAGRAM}} +``` + +--- + +## 4. Solution Strategy + +### 4.1 Technology Decisions +{{TECHNOLOGY_DECISIONS}} + + +### 4.2 Top-Level Decomposition +{{TOP_LEVEL_DECOMPOSITION}} + + +### 4.3 Approach to Quality Goals +{{QUALITY_APPROACH}} + + +--- + +## 5. Building Block View + +### 5.1 Level 1: System Context (C4 Model) +{{SYSTEM_CONTEXT}} + + +**System Context Diagram:** +```mermaid +{{SYSTEM_CONTEXT_DIAGRAM}} +``` + +### 5.2 Level 2: Container Diagram (C4 Model) +{{CONTAINER_DIAGRAM}} + + +**Container Diagram:** +```mermaid +{{CONTAINER_DIAGRAM_MERMAID}} +``` + +### 5.3 Level 3: Component Diagram (C4 Model) +{{COMPONENT_DIAGRAM}} + + +**Components within API Container:** +```mermaid +{{COMPONENT_DIAGRAM_MERMAID}} +``` + +**Key Components:** +{{KEY_COMPONENTS}} + + +**Infrastructure Layer Components:** +{{INFRASTRUCTURE_COMPONENTS}} + + +--- + +## 6. Runtime View + +### 6.1 Scenario 1: User Registration +{{SCENARIO_USER_REGISTRATION}} + + +**Sequence Diagram:** +```mermaid +{{SCENARIO_1_SEQUENCE_DIAGRAM}} +``` + +### 6.2 Scenario 2: Product Purchase Flow +{{SCENARIO_PURCHASE_FLOW}} + + +**Sequence Diagram:** +```mermaid +{{SCENARIO_2_SEQUENCE_DIAGRAM}} +``` + +### 6.3 [Additional Key Scenarios] +{{ADDITIONAL_SCENARIOS}} + + +--- + +## 7. Crosscutting Concepts + +### 7.1 Security Concept +{{SECURITY_CONCEPT}} + + +### 7.2 Error Handling Concept +{{ERROR_HANDLING_CONCEPT}} + + +### 7.3 Configuration Management Concept +{{CONFIG_MANAGEMENT_CONCEPT}} + + +### 7.4 Data Access Pattern +{{DATA_ACCESS_PATTERN}} + + +--- + +## 8. Architecture Decisions (ADRs) + +{{ADR_LIST}} + + +**Critical ADRs Summary:** +{{CRITICAL_ADRS_SUMMARY}} + + +--- + +## 9. Quality Requirements + +### 9.1 Quality Tree +{{QUALITY_TREE}} + + +### 9.2 Quality Scenarios +{{QUALITY_SCENARIOS}} + + +--- + +## 10. Risks and Technical Debt + +### 10.1 Known Technical Risks +{{TECHNICAL_RISKS}} + + +### 10.2 Technical Debt +{{TECHNICAL_DEBT}} + + +### 10.3 Mitigation Strategies +{{MITIGATION_STRATEGIES}} + + +--- + +## 11. Glossary + +| Term | Definition | +|------|------------| +| {{TERM_1}} | {{DEFINITION_1}} | +| Container | Deployable/runnable unit (C4 Model), NOT Docker container | +| Component | Grouping of related functionality within a container | +| SSR | Server-Side Rendering | +| RBAC | Role-Based Access Control | +| JWT | JSON Web Token | + +--- + +## 12. References + +1. arc42 Architecture Template v8.2 - https://arc42.org/ +2. C4 Model for Visualizing Software Architecture - https://c4model.com/ +3. ISO/IEC/IEEE 42010:2022 - Architecture description +4. Michael Nygard's ADR Format - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions +5. {{PROJECT_NAME}} Requirements Document +6. {{PROJECT_NAME}} ADRs Directory + +--- + +## Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New architectural decisions (create new ADR, update Section 8) +- New microservices or containers added (update C4 Container diagram) +- New components in existing services (update C4 Component diagram) +- New external systems or integrations (update Context diagram) +- Major refactoring affecting system structure +- Changes to quality requirements or scenarios + +**Verification:** +- [ ] All C4 diagrams (Context, Container, Component) are consistent +- [ ] All ADRs referenced in Section 8 exist in adrs/ directory +- [ ] Runtime view scenarios cover main use cases +- [ ] All external systems documented in Technical Context +- [ ] All placeholders replaced with actual content + +--- + +## Revision History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | {{DATE}} | {{AUTHOR}} | Initial version | + +--- + +**Version:** 4.0.0 (Added Infrastructure Layer guidance: Section 5.3 Infrastructure Components + Section 7.4 Data Access Pattern) +**Template Last Updated:** 2025-11-18 diff --git a/skills/ln-114-project-docs-creator/references/templates/database_schema_template.md b/skills/ln-114-project-docs-creator/references/templates/database_schema_template.md new file mode 100644 index 0000000..4948d26 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/database_schema_template.md @@ -0,0 +1,293 @@ +# Database Schema: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} + + + + +--- + +## 1. Introduction + +### 1.1 Purpose +This document specifies the database schema, entity relationships, and data dictionary for {{PROJECT_NAME}}. + +### 1.2 Database System +{{DATABASE_SYSTEM}} + + +### 1.3 Normalization Level +{{NORMALIZATION_LEVEL}} + + +--- + +## 2. Entity Relationship Diagram + +### 2.1 High-Level ER Diagram + +```mermaid +erDiagram + {{ER_DIAGRAM_ENTITIES_RELATIONSHIPS}} +``` + + + +--- + +## 3. Data Dictionary + +### 3.1 {{TABLE_1}} Table + +**Table Name:** `{{table_1}}` +**Description:** {{TABLE_1_DESCRIPTION}} + + +| Column | Type | Null | Default | Constraints | Description | +|--------|------|------|---------|-------------|-------------| +| `id` | UUID | NO | gen_random_uuid() | PRIMARY KEY | Unique user identifier | +| `email` | VARCHAR(255) | NO | - | UNIQUE, CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$') | User email address | +| `password_hash` | VARCHAR(255) | NO | - | - | bcrypt hashed password | +| `first_name` | VARCHAR(100) | YES | NULL | - | User first name | +| `last_name` | VARCHAR(100) | YES | NULL | - | User last name | +| `role` | VARCHAR(20) | NO | 'viewer' | CHECK (role IN ('admin', 'editor', 'viewer')) | User role for RBAC | +| `is_active` | BOOLEAN | NO | TRUE | - | Account status | +| `created_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | - | Account creation timestamp | +| `updated_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP | Last update timestamp | + +**Indexes:** +```sql +CREATE UNIQUE INDEX idx_users_email ON users(email); +CREATE INDEX idx_users_role ON users(role); +CREATE INDEX idx_users_created_at ON users(created_at); +``` + +**Relationships:** +- `users.id` → `orders.user_id` (One-to-Many) +- `users.id` → `reviews.user_id` (One-to-Many) + +--- + +### 3.2 {{TABLE_2}} Table + +**Table Name:** `{{table_2}}` +**Description:** {{TABLE_2_DESCRIPTION}} + + +| Column | Type | Null | Default | Constraints | Description | +|--------|------|------|---------|-------------|-------------| +| `id` | UUID | NO | gen_random_uuid() | PRIMARY KEY | Product identifier | +| `category_id` | UUID | NO | - | FOREIGN KEY REFERENCES categories(id) ON DELETE RESTRICT | Product category | +| `name` | VARCHAR(200) | NO | - | - | Product name | +| `slug` | VARCHAR(220) | NO | - | UNIQUE | URL-friendly name | +| `description` | TEXT | YES | NULL | - | Product description | +| `price` | DECIMAL(10,2) | NO | - | CHECK (price >= 0) | Product price (USD) | +| `stock_quantity` | INTEGER | NO | 0 | CHECK (stock_quantity >= 0) | Available inventory | +| `is_published` | BOOLEAN | NO | FALSE | - | Publish status | +| `created_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | - | Creation timestamp | +| `updated_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP | Last update timestamp | + +**Indexes:** +```sql +CREATE UNIQUE INDEX idx_products_slug ON products(slug); +CREATE INDEX idx_products_category_id ON products(category_id); +CREATE INDEX idx_products_is_published ON products(is_published); +CREATE INDEX idx_products_price ON products(price); +``` + +**Relationships:** +- `categories.id` → `products.category_id` (One-to-Many) +- `products.id` → `order_items.product_id` (One-to-Many) +- `products.id` → `reviews.product_id` (One-to-Many) + +--- + +### 3.3 {{TABLE_3}} Table + +{{TABLE_3_DEFINITION}} + + +--- + +## 4. Database Constraints + +### 4.1 Foreign Key Constraints + +| FK Name | Child Table | Child Column | Parent Table | Parent Column | On Delete | On Update | +|---------|-------------|--------------|--------------|---------------|-----------|-----------| +| `fk_orders_user` | orders | user_id | users | id | CASCADE | CASCADE | +| `fk_products_category` | products | category_id | categories | id | RESTRICT | CASCADE | +| `fk_order_items_order` | order_items | order_id | orders | id | CASCADE | CASCADE | +| `fk_order_items_product` | order_items | product_id | products | id | RESTRICT | CASCADE | + + + +### 4.2 Check Constraints + +| Constraint Name | Table | Expression | Description | +|-----------------|-------|------------|-------------| +| `chk_users_role` | users | `role IN ('admin', 'editor', 'viewer')` | Valid role values | +| `chk_products_price` | products | `price >= 0` | Non-negative price | +| `chk_products_stock` | products | `stock_quantity >= 0` | Non-negative stock | +| `chk_orders_status` | orders | `status IN ('pending', 'paid', 'shipped', 'delivered', 'canceled')` | Valid order statuses | + +--- + +## 5. Indexes Strategy + +### 5.1 Primary Indexes +{{PRIMARY_INDEXES}} + + +### 5.2 Secondary Indexes +{{SECONDARY_INDEXES}} + + +### 5.3 Composite Indexes +{{COMPOSITE_INDEXES}} + + +--- + +## 6. Database Migrations + +### 6.1 Migration Tool +{{MIGRATION_TOOL}} + + +### 6.2 Migration Strategy +{{MIGRATION_STRATEGY}} + + +### 6.3 Migration Examples + +**Migration 001: Initial Schema** +```sql +-- Up Migration +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + email VARCHAR(255) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + role VARCHAR(20) NOT NULL DEFAULT 'viewer', + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP +); + +-- Down Migration +DROP TABLE IF EXISTS users; +``` + +**Migration 002: Add Soft Delete** +```sql +-- Up Migration +ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP NULL; +CREATE INDEX idx_users_deleted_at ON users(deleted_at); + +-- Down Migration +ALTER TABLE users DROP COLUMN deleted_at; +``` + +--- + +## 7. Data Types & Standards + +### 7.1 Common Data Types + +| Logical Type | PostgreSQL Type | MySQL Type | Description | +|--------------|----------------|------------|-------------| +| UUID | UUID | CHAR(36) | Unique identifiers | +| Money | DECIMAL(10,2) | DECIMAL(10,2) | Currency values (2 decimal places) | +| Timestamp | TIMESTAMP | DATETIME | Date and time (UTC) | +| Boolean | BOOLEAN | TINYINT(1) | True/false values | +| JSON | JSONB | JSON | Semi-structured data | + +### 7.2 Naming Conventions +{{NAMING_CONVENTIONS}} + + +--- + +## 8. Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New tables added +- Schema changes (columns, indexes, constraints) +- Migration scripts created +- Denormalization for performance +- Relationship changes + +**Verification:** +- [ ] All tables documented with columns/types/constraints +- [ ] ER diagram matches actual schema +- [ ] Indexes match query patterns +- [ ] Foreign keys enforce referential integrity +- [ ] Migrations tested (up + down) + +--- + +**Version:** 1.0.0 +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-114-project-docs-creator/references/templates/design_guidelines_template.md b/skills/ln-114-project-docs-creator/references/templates/design_guidelines_template.md new file mode 100644 index 0000000..4bfad32 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/design_guidelines_template.md @@ -0,0 +1,351 @@ +# Design Guidelines: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} + + + + +--- + +## 1. Design Approach + +### 1.1 Design Philosophy +{{DESIGN_PHILOSOPHY}} + + +### 1.2 Design Inspiration +{{DESIGN_INSPIRATION}} + + +--- + +## 2. Core Design Elements + +### 2.1 Typography + +**Font Families:** +{{FONT_FAMILIES}} + + +**Type Scale:** +{{TYPE_SCALE}} + + +**Line Height:** +{{LINE_HEIGHT}} + + +--- + +### 2.2 Color System + +**Primary Colors:** +{{PRIMARY_COLORS}} + + +**Semantic Colors:** +{{SEMANTIC_COLORS}} + + +**Neutral Colors:** +{{NEUTRAL_COLORS}} + + +**Color Accessibility:** +{{COLOR_ACCESSIBILITY}} + + +--- + +### 2.3 Layout System + +**Spacing Primitives:** +{{SPACING_SYSTEM}} + + +**Container Strategy:** +{{CONTAINER_STRATEGY}} + + +**Grid System:** +{{GRID_SYSTEM}} + + +--- + +### 2.4 Component Library + +#### 2.4.1 Navigation + +{{NAVIGATION_COMPONENTS}} + + +#### 2.4.2 Buttons + +{{BUTTON_COMPONENTS}} + + +#### 2.4.3 Forms + +{{FORM_COMPONENTS}} + + +#### 2.4.4 Cards + +{{CARD_COMPONENTS}} + + +#### 2.4.5 Modals & Dialogs + +{{MODAL_COMPONENTS}} + + +#### 2.4.6 Tables + +{{TABLE_COMPONENTS}} + + +--- + +### 2.5 Responsive Behavior + +**Breakpoints:** +{{BREAKPOINTS}} + + +**Layout Adaptations:** +{{RESPONSIVE_LAYOUTS}} + + +--- + +## 3. Accessibility Guidelines + +### 3.1 WCAG Compliance +{{WCAG_LEVEL}} + + +### 3.2 Keyboard Navigation +{{KEYBOARD_NAVIGATION}} + + +### 3.3 Screen Reader Support +{{SCREEN_READER}} + + +### 3.4 Focus Management +{{FOCUS_MANAGEMENT}} + + +--- + +## 4. Branding & Visual Identity + +### 4.1 Logo Usage +{{LOGO_USAGE}} + + +### 4.2 Imagery Guidelines +{{IMAGERY_GUIDELINES}} + + +### 4.3 Iconography +{{ICONOGRAPHY}} + + +--- + +## 5. Page Layout Patterns + +### 5.1 {{PAGE_TYPE_1}} +{{PAGE_LAYOUT_1}} + + +### 5.2 {{PAGE_TYPE_2}} +{{PAGE_LAYOUT_2}} + + +### 5.3 {{PAGE_TYPE_3}} +{{PAGE_LAYOUT_3}} + + +--- + +## 6. Internationalization (if applicable) + +{{I18N_GUIDELINES}} + + +--- + +## 7. Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New component added to design system +- Brand refresh or logo change +- Accessibility audit findings +- Design system library update (Material UI, Ant Design, etc.) +- Responsive breakpoint changes +- Color palette modifications + +**Verification:** +- [ ] All components documented with examples +- [ ] Color contrast ratios WCAG AA compliant (4.5:1 text, 3:1 UI) +- [ ] Typography scale consistent across platform +- [ ] Accessibility guidelines up to date +- [ ] Responsive behaviors tested on all breakpoints +- [ ] Logo usage rules followed + +--- + +**Version:** 1.0.0 +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-114-project-docs-creator/references/templates/requirements_template.md b/skills/ln-114-project-docs-creator/references/templates/requirements_template.md new file mode 100644 index 0000000..1d1fc9e --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/requirements_template.md @@ -0,0 +1,168 @@ +# Requirements Specification: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} +**Standard Compliance:** ISO/IEC/IEEE 29148:2018 + + + + +--- + +## 1. Introduction + +### 1.1 Purpose +This document specifies the functional requirements for {{PROJECT_NAME}}. + +### 1.2 Scope +{{PROJECT_SCOPE}} + + +### 1.3 Intended Audience +- Development Team +- QA Team +- DevOps Team +- Technical Writers +- System Architects + +### 1.4 References +- Project Charter: {{PROJECT_CHARTER_LINK}} +- Architecture Document: {{ARCHITECTURE_DOC_LINK}} +- Definition of Done: {{DOD_LINK}} + +--- + +## 2. Overall Description + +### 2.1 Product Perspective +{{PRODUCT_PERSPECTIVE}} + + +### 2.2 User Classes and Characteristics +{{USER_CLASSES}} + + +### 2.3 Operating Environment +{{OPERATING_ENVIRONMENT}} + + +--- + +## 3. Functional Requirements + +### 3.1 User Management +{{FR_USER_MANAGEMENT}} + + +### 3.2 [Feature Group 2] +{{FR_FEATURE_GROUP_2}} + + +### 3.3 [Feature Group 3] +{{FR_FEATURE_GROUP_3}} + + +--- + +## 4. Acceptance Criteria (High-Level) + +{{HIGH_LEVEL_ACCEPTANCE_CRITERIA}} + + +--- + +## 5. Constraints + +### 5.1 Technical Constraints +{{TECHNICAL_CONSTRAINTS}} + + +### 5.2 Regulatory Constraints +{{REGULATORY_CONSTRAINTS}} + + +--- + +## 6. Assumptions and Dependencies + +### 6.1 Assumptions +{{ASSUMPTIONS}} + + +### 6.2 Dependencies +{{DEPENDENCIES}} + + +--- + +## 7. Requirements Traceability + +| Requirement ID | Epic | User Story | Test Case | Status | +|---------------|------|------------|-----------|--------| +| FR-UM-001 | Epic-001 | US-001 | TC-001 | {{STATUS}} | + + +--- + +## 8. Glossary + +| Term | Definition | +|------|------------| +| {{TERM_1}} | {{DEFINITION_1}} | + + +--- + +## 9. Appendices + +### Appendix A: MoSCoW Prioritization Summary +- **MUST have**: {{MUST_COUNT}} requirements +- **SHOULD have**: {{SHOULD_COUNT}} requirements +- **COULD have**: {{COULD_COUNT}} requirements +- **WON'T have (this release)**: {{WONT_COUNT}} requirements + + +### Appendix B: References +1. ISO/IEC/IEEE 29148:2018 - Systems and software engineering +2. OWASP ASVS (Application Security Verification Standard) +3. WCAG 2.1 (Web Content Accessibility Guidelines) + +--- + +## Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New functional requirements identified during development +- New constraints or dependencies discovered +- Stakeholder feedback on requirements clarity +- Post-release feedback requiring requirement modifications +- MoSCoW prioritization changes + +**Verification:** +- [ ] All FR-XXX-NNN requirements have acceptance criteria +- [ ] All FR-XXX-NNN requirements have MoSCoW priority (MUST/SHOULD/COULD/WON'T) +- [ ] Traceability matrix links requirements to epics/stories +- [ ] No orphaned requirements (all linked to business value) +- [ ] All placeholders replaced with actual content + +--- + +## Revision History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | {{DATE}} | {{AUTHOR}} | Initial version | + +--- + +**Version:** 3.0.0 (BREAKING: NFR sections removed completely per project policy) +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-114-project-docs-creator/references/templates/runbook_template.md b/skills/ln-114-project-docs-creator/references/templates/runbook_template.md new file mode 100644 index 0000000..96eb7b3 --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/runbook_template.md @@ -0,0 +1,632 @@ +# Operations Runbook: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} + + + + +--- + +## 1. Overview + +### 1.1 Purpose +This runbook provides step-by-step operational procedures for {{PROJECT_NAME}} across all environments: local development, testing, and production. + +### 1.2 Quick Links +- Architecture: {{ARCHITECTURE_LINK}} +- Tech Stack: {{TECH_STACK_LINK}} +- API Spec: {{API_SPEC_LINK}} +- Database Schema: {{DATABASE_SCHEMA_LINK}} + +### 1.3 Key Contacts +{{KEY_CONTACTS}} + + +--- + +## 2. Prerequisites + +### 2.1 Required Tools +{{REQUIRED_TOOLS}} + + +### 2.2 Access Requirements +{{ACCESS_REQUIREMENTS}} + + +### 2.3 Environment Variables +See [Appendix A: Environment Variables](#appendix-a-environment-variables-reference) for complete reference. + +--- + +## 3. Local Development + +### 3.1 Initial Setup + +```bash +# Clone repository +git clone https://github.com/org/{{PROJECT_NAME}}.git +cd {{PROJECT_NAME}} + +# Copy environment template +cp .env.example .env + +# Edit .env with your credentials +# See Appendix A for required variables + +# Build and start services +docker compose up -d + +# Wait for services to be ready (check logs) +docker compose logs -f app +``` + +**Expected output:** +``` +app-1 | Server started on port 3000 +db-1 | database system is ready to accept connections +``` + +### 3.2 Docker Commands + +**Start all services:** +```bash +docker compose up -d +``` + +**Stop all services:** +```bash +docker compose down +``` + +**Rebuild after code changes:** +```bash +docker compose down +docker compose build --no-cache app +docker compose up -d +``` + +**View logs:** +```bash +# All services +docker compose logs -f + +# Specific service +docker compose logs -f app + +# Last 100 lines +docker compose logs --tail 100 app +``` + +**Exec into running container:** +```bash +docker compose exec app sh +# or +docker compose exec app bash +``` + +**Restart specific service:** +```bash +docker compose restart app +``` + +### 3.3 Database Operations (Local) + +**Run migrations:** +```bash +docker compose exec app npm run migrate + +# Or using Prisma +docker compose exec app npx prisma migrate dev +``` + +**Seed database:** +```bash +docker compose exec app npm run seed +``` + +**Reset database (⚠️ DESTRUCTIVE):** +```bash +docker compose down +docker volume rm {{PROJECT_NAME}}_postgres_data +docker compose up -d +docker compose exec app npm run migrate +docker compose exec app npm run seed +``` + +**Database shell:** +```bash +# PostgreSQL +docker compose exec db psql -U {{DB_USER}} -d {{DB_NAME}} + +# MySQL +docker compose exec db mysql -u {{DB_USER}} -p{{DB_PASSWORD}} {{DB_NAME}} +``` + +### 3.4 Common Development Tasks + +**Install dependencies (after package.json changes):** +```bash +docker compose down +docker compose build app +docker compose up -d +``` + +**Run linter:** +```bash +docker compose exec app npm run lint + +# Fix automatically +docker compose exec app npm run lint:fix +``` + +**Format code:** +```bash +docker compose exec app npm run format +``` + +**Check syntax (TypeScript):** +```bash +docker compose exec app npm run type-check +``` + +--- + +## 4. Testing + +### 4.1 Run All Tests + +```bash +# Using docker-compose.test.yml +docker compose -f docker-compose.test.yml up --abort-on-container-exit +``` + +### 4.2 Run Specific Test Types + +**Unit tests:** +```bash +docker compose exec app npm run test:unit + +# Watch mode +docker compose exec app npm run test:unit:watch +``` + +**Integration tests:** +```bash +docker compose exec app npm run test:integration +``` + +**E2E tests:** +```bash +# Start app first +docker compose up -d + +# Run E2E +docker compose exec app npm run test:e2e +``` + +### 4.3 Test Coverage + +```bash +docker compose exec app npm run test:coverage + +# Open coverage report +open coverage/index.html +``` + +### 4.4 Debug Tests + +```bash +# Run single test file +docker compose exec app npm test -- path/to/test.spec.ts + +# Run with debugging +docker compose exec app node --inspect-brk=0.0.0.0:9229 node_modules/.bin/jest +``` + +--- + +## 5. Build & Deployment + +### 5.1 Build for Production + +```bash +# Build production image +docker build -t {{PROJECT_NAME}}:{{VERSION}} . + +# Test production build locally +docker run -p 3000:3000 --env-file .env.production {{PROJECT_NAME}}:{{VERSION}} +``` + +### 5.2 Deployment to Production + +{{DEPLOYMENT_PROCEDURE}} + + +--- + +## 6. Production Operations + +### 6.1 SSH Access + +**SSH to production server:** +```bash +ssh {{PRODUCTION_USER}}@{{PRODUCTION_HOST}} + +# Or with SSH key +ssh -i ~/.ssh/{{PROJECT_NAME}}_prod.pem {{PRODUCTION_USER}}@{{PRODUCTION_HOST}} +``` + +**SSH via jump host (if behind VPN):** +```bash +ssh -J {{JUMP_HOST}} {{PRODUCTION_USER}}@{{PRODUCTION_HOST}} +``` + +### 6.2 Health Checks + +**Check application status:** +```bash +# Health endpoint +curl http://localhost:3000/health + +# Expected response: +# {"status": "ok", "uptime": 123456, "timestamp": "2024-01-01T00:00:00Z"} +``` + +**Check service status:** +```bash +docker compose ps + +# Expected output: +# NAME STATUS PORTS +# app-1 Up 5 minutes 0.0.0.0:3000->3000/tcp +# db-1 Up 5 minutes 5432/tcp +# cache-1 Up 5 minutes 6379/tcp +``` + +**Check resource usage:** +```bash +docker stats + +# Or specific container +docker stats app-1 +``` + +### 6.3 Monitoring & Logs + +**View logs:** +```bash +# Real-time logs (all services) +docker compose logs -f + +# Last 500 lines from app +docker compose logs --tail 500 app + +# Logs from specific time +docker compose logs --since 2024-01-01T00:00:00 app + +# Save logs to file +docker compose logs --no-color app > app-logs-$(date +%Y%m%d).log +``` + +**Search logs:** +```bash +# Find errors +docker compose logs app | grep ERROR + +# Find specific request +docker compose logs app | grep "request_id=123" +``` + +**Log rotation:** +{{LOG_ROTATION}} + + +### 6.4 Common Maintenance Tasks + +**Restart application (zero downtime):** +```bash +docker compose up -d --no-deps --force-recreate app +``` + +**Clear cache:** +```bash +docker compose exec cache redis-cli FLUSHALL +``` + +**Database backup:** +```bash +# PostgreSQL +docker compose exec db pg_dump -U {{DB_USER}} {{DB_NAME}} > backup-$(date +%Y%m%d-%H%M%S).sql + +# MySQL +docker compose exec db mysqldump -u {{DB_USER}} -p{{DB_PASSWORD}} {{DB_NAME}} > backup-$(date +%Y%m%d-%H%M%S).sql +``` + +**Database restore:** +```bash +# PostgreSQL +cat backup-20240101-120000.sql | docker compose exec -T db psql -U {{DB_USER}} {{DB_NAME}} + +# MySQL +cat backup-20240101-120000.sql | docker compose exec -T db mysql -u {{DB_USER}} -p{{DB_PASSWORD}} {{DB_NAME}} +``` + +**Update dependencies:** +```bash +# Update package.json +docker compose exec app npm update + +# Rebuild image +docker compose down +docker compose build --no-cache app +docker compose up -d +``` + +--- + +## 7. Troubleshooting + +### 7.1 Common Issues + +#### Issue 1: Application won't start + +**Symptoms:** +``` +app-1 | Error: Cannot connect to database +app-1 | Error: ECONNREFUSED +``` + +**Diagnosis:** +```bash +# Check if database is running +docker compose ps db + +# Check database logs +docker compose logs db + +# Test database connection +docker compose exec app nc -zv db 5432 +``` + +**Resolution:** +```bash +# Restart database +docker compose restart db + +# Wait for database to be ready +docker compose logs -f db +# Look for: "database system is ready to accept connections" + +# Restart app +docker compose restart app +``` + +--- + +#### Issue 2: Out of disk space + +**Symptoms:** +``` +Error: no space left on device +``` + +**Diagnosis:** +```bash +df -h +docker system df +``` + +**Resolution:** +```bash +# Remove unused Docker resources +docker system prune -a + +# Remove specific volumes (⚠️ DESTRUCTIVE) +docker volume rm {{PROJECT_NAME}}_postgres_data + +# Remove old log files +find /var/log -name "*.log" -mtime +30 -delete +``` + +--- + +#### Issue 3: {{ISSUE_3_NAME}} +{{ISSUE_3_TROUBLESHOOTING}} + + +--- + +### 7.2 Emergency Procedures + +**Production outage:** +```bash +# 1. Check health status +curl http://localhost:3000/health + +# 2. Check logs for errors +docker compose logs --tail 200 app | grep ERROR + +# 3. Restart services +docker compose restart + +# 4. If restart fails, rollback +git reset --hard HEAD~1 +docker compose down && docker compose up -d + +# 5. Notify team (Slack/PagerDuty) +``` + +**Database corruption:** +```bash +# 1. Stop application +docker compose stop app + +# 2. Restore from latest backup +./scripts/restore-db.sh {{LATEST_BACKUP}} + +# 3. Verify data integrity +docker compose exec db psql -U {{DB_USER}} -d {{DB_NAME}} -c "SELECT COUNT(*) FROM users;" + +# 4. Restart application +docker compose start app +``` + +--- + +## 8. Appendices + +### Appendix A: Environment Variables Reference + +**Required variables:** + +| Variable | Example | Description | +|----------|---------|-------------| +| `DATABASE_URL` | `postgresql://user:pass@db:5432/myapp` | Database connection string | +| `REDIS_URL` | `redis://cache:6379` | Cache connection string | +| `API_KEY` | `sk_live_abc123...` | External API key (e.g., Stripe) | +| `JWT_SECRET` | `random_secret_key` | JWT signing secret | +| `NODE_ENV` | `development` or `production` | Environment mode | + +**Optional variables:** + +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | `3000` | Application port | +| `LOG_LEVEL` | `info` | Logging verbosity (debug/info/warn/error) | +| `RATE_LIMIT` | `100` | API rate limit (requests/minute) | + +--- + +### Appendix B: Service Dependencies + +{{SERVICE_DEPENDENCIES}} + + +--- + +### Appendix C: Port Mapping + +{{PORT_MAPPING}} + + +--- + +## 9. Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- New deployment procedures +- Infrastructure changes (new services, ports) +- New operational commands +- Troubleshooting scenarios discovered +- Environment variable changes +- SSH access changes + +**Verification:** +- [ ] All commands tested in staging +- [ ] SSH access verified +- [ ] Health check procedures validated +- [ ] Backup/restore procedures tested +- [ ] Emergency procedures reviewed +- [ ] Contact information current + +--- + +**Version:** 1.0.0 +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-114-project-docs-creator/references/templates/tech_stack_template.md b/skills/ln-114-project-docs-creator/references/templates/tech_stack_template.md new file mode 100644 index 0000000..4f09d4d --- /dev/null +++ b/skills/ln-114-project-docs-creator/references/templates/tech_stack_template.md @@ -0,0 +1,249 @@ +# Technology Stack: {{PROJECT_NAME}} + +**Document Version:** 1.0 +**Date:** {{DATE}} +**Status:** {{STATUS}} + + + + +--- + +## 1. Introduction + +### 1.1 Purpose +This document specifies the technology stack, frameworks, libraries, and tools used in {{PROJECT_NAME}}. + +### 1.2 Scope +{{SCOPE}} + + +--- + +## 2. Technology Stack + +### 2.1 Stack Overview + +| Layer | Technology | Version | Rationale | ADR | +|-------|------------|---------|-----------|-----| +| **Frontend** | {{FRONTEND_FRAMEWORK}} | {{FRONTEND_VERSION}} | {{FRONTEND_RATIONALE}} | {{FRONTEND_ADR_LINK}} | +| **Backend** | {{BACKEND_FRAMEWORK}} | {{BACKEND_VERSION}} | {{BACKEND_RATIONALE}} | {{BACKEND_ADR_LINK}} | +| **Database** | {{DATABASE}} | {{DATABASE_VERSION}} | {{DATABASE_RATIONALE}} | {{DATABASE_ADR_LINK}} | +| **Cache** | {{CACHE}} | {{CACHE_VERSION}} | {{CACHE_RATIONALE}} | {{CACHE_ADR_LINK}} | +| **Message Queue** | {{QUEUE}} | {{QUEUE_VERSION}} | {{QUEUE_RATIONALE}} | {{QUEUE_ADR_LINK}} | +| **Testing** | {{TEST_FRAMEWORK}} | {{TEST_VERSION}} | {{TEST_RATIONALE}} | {{TEST_ADR_LINK}} | +| **DevOps** | {{DEVOPS_TOOLS}} | {{DEVOPS_VERSION}} | {{DEVOPS_RATIONALE}} | {{DEVOPS_ADR_LINK}} | + + + +### 2.2 Key Libraries & Dependencies + +**Frontend:** +{{FRONTEND_LIBRARIES}} + + +**Backend:** +{{BACKEND_LIBRARIES}} + + +**Common:** +{{COMMON_LIBRARIES}} + + +--- + +## 3. Docker Development Environment + +### 3.1 Dockerfile + +```dockerfile +{{DOCKERFILE_CONTENT}} +``` + + + +### 3.2 docker-compose.yml (Development) + +```yaml +{{DOCKER_COMPOSE_DEV}} +``` + + + +### 3.3 docker-compose.test.yml (Testing) + +```yaml +{{DOCKER_COMPOSE_TEST}} +``` + + + +--- + +## 4. Development Tools + +### 4.1 Required Tools + +| Tool | Version | Purpose | Installation | +|------|---------|---------|--------------| +| Node.js | {{NODE_VERSION}} | Runtime environment | https://nodejs.org/ | +| Docker | 24.0+ | Container runtime | https://docs.docker.com/get-docker/ | +| Git | 2.40+ | Version control | https://git-scm.com/ | +| {{IDE}} | Latest | Code editor | {{IDE_LINK}} | + + + +### 4.2 VS Code Extensions (Recommended) + +{{VSCODE_EXTENSIONS}} + + +### 4.3 Linters & Code Quality Tools + +| Tool | Version | Purpose | Command | Config File | +|------|---------|---------|---------|-------------| +| {{LINTER_1}} | {{VERSION_1}} | {{PURPOSE_1}} | {{COMMAND_1}} | {{CONFIG_1}} | + + + +**CI/CD Integration:** +{{CI_LINT_INTEGRATION}} + + +**Run All Quality Checks:** +```bash +{{LINT_ALL_COMMAND}} +``` + + +--- + +## 5. Naming Conventions + +### 5.1 File Naming +{{FILE_NAMING}} + + +### 5.2 Variable Naming +{{VARIABLE_NAMING}} + + +### 5.3 Database Naming +{{DATABASE_NAMING}} + + +--- + +## 6. Maintenance + +**Last Updated:** {{DATE}} + +**Update Triggers:** +- Technology version upgrade (major/minor releases) +- New library added to dependencies +- Docker configuration changes +- Development tool updates + +**Verification:** +- [ ] All versions match package.json/Dockerfile +- [ ] ADR links valid and point to correct decisions +- [ ] Docker compose files tested and working +- [ ] All listed tools accessible with installation links + +--- + +**Version:** 1.0.0 +**Template Last Updated:** 2025-11-16 diff --git a/skills/ln-115-presentation-creator/SKILL.md b/skills/ln-115-presentation-creator/SKILL.md new file mode 100644 index 0000000..9d58ad6 --- /dev/null +++ b/skills/ln-115-presentation-creator/SKILL.md @@ -0,0 +1,785 @@ +--- +name: ln-115-presentation-creator +description: Builds interactive HTML presentation with 6 tabs (Overview, Requirements, Architecture/C4, Tech Spec, Roadmap, Guides). Creates presentation/README.md hub. Worker under ln-110-documents-pipeline. +--- + +# HTML Presentation Builder + +This skill creates an interactive, self-contained HTML presentation from existing project documentation. It transforms Markdown documents into a professional, navigable web presentation with diagrams, collapsible sections, and modern UI. + +## When to Use This Skill + +**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator OR used standalone. + +Use this skill when: +- Building HTML presentation from existing documentation +- Rebuilding presentation after documentation updates +- Creating standalone presentation for sharing (no full documentation setup needed) +- Validating that source documentation is ready for presentation generation + +**Part of workflow**: ln-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → ln-114-project-docs-creator → **ln-115-presentation-creator** + +**Prerequisites**: Existing documentation in `docs/` directory with **required files**: +- `docs/project/requirements.md` (REQUIRED) +- `docs/project/architecture.md` (REQUIRED) +- `docs/project/tech_stack.md` (REQUIRED) + +**Optional files** (enhance presentation but not blocking): +- `docs/project/api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md` +- `docs/reference/adrs/*.md` (ADRs with Category: Strategic|Technical) +- `docs/reference/guides/*.md` (How-to guides) +- `docs/tasks/kanban_board.md` (Epic Story Counters for Roadmap) + +## How It Works + +The skill follows a **7-phase workflow**: READ DOCS → VALIDATE SOURCE EXISTS → VALIDATE SOURCE QUALITY → CREATE DIR → COPY TEMPLATES → INJECT CONTENT → BUILD HTML. + +**Phase 1: READ DOCS** - Load all project documentation from docs/ +**Phase 2: VALIDATE SOURCE EXISTS** - Check required files exist (requirements.md, architecture.md, tech_stack.md), warn if optional missing +**Phase 3: VALIDATE SOURCE QUALITY** - Check diagrams, placeholders, content length (read-only validation) +**Phase 4: CREATE DIR** - Create presentation/ directory + README.md navigation hub +**Phase 5: COPY TEMPLATES** - Copy HTML/CSS/JS templates to assets/ +**Phase 6: INJECT CONTENT** - Parse MD docs → replace placeholders in tab files → delete example blocks +**Phase 7: BUILD HTML** - Assemble modular components into standalone presentation_final.html + +--- + +## Phase 1: Read Documentation + +**Objective**: Load all project documentation for transformation. + +**When to execute**: Always (first phase) + +**Process**: + +1. **Use docs/ as source**: + - Read documentation from `docs/project/`, `docs/reference/`, `docs/tasks/` directories + - Standard locations created by ln-114, ln-112, ln-113 + +2. **Read Core MD Documents**: + - `project/requirements.md` - Functional Requirements + - `project/architecture.md` - Architecture design, C4 diagrams + - `project/tech_stack.md` - Technology versions, Docker configuration + - `project/api_spec.md` - API endpoints, authentication (if exists) + - `project/database_schema.md` - Database schema, ER diagrams (if exists) + - `project/design_guidelines.md` - UI/UX design system (if exists) + - `project/runbook.md` - Operational procedures (if exists) + +3. **Read ADRs** (if exist): + - `reference/adrs/adr-001-*.md` through `adr-NNN-*.md` + - Parse ADR metadata (status, date, title, Category: Strategic|Technical) + +4. **Read Guides** (if exist): + - `reference/guides/*.md` - How-to guides for Guides tab + +5. **Read Kanban Board** (if exists): + - `tasks/kanban_board.md` - Epic Story Counters table for Roadmap progress + +6. **Extract metadata**: + - Project name, date, version from documents + - Preserve Mermaid diagram blocks + +**Output**: Loaded documentation data ready for validation and HTML generation + +--- + +## Phase 2: Validate Source Documentation Exists + +**Objective**: Verify that required source documentation exists before building presentation. Prevent building incomplete presentations. + +**When to execute**: After Phase 1 (documentation loaded) + +**Process**: + +### 2.1 Check required files + +**REQUIRED** (must exist - block execution if missing): +- ✅ `docs/project/requirements.md` +- ✅ `docs/project/architecture.md` +- ✅ `docs/project/tech_stack.md` + +For each required file: +1. Use Glob tool: `pattern: "docs/project/{filename}"` +2. If NOT found: + - Add to missing list +3. If found: + - Check file size > 100 bytes (not empty) + +**If ANY required file missing or empty:** +``` +❌ ERROR: Cannot build presentation - missing required documentation: + - docs/project/requirements.md [missing/empty] + - docs/project/architecture.md [missing/empty] + +Suggestion: Run ln-114-project-docs-creator to create missing files. + +STOP execution. +``` + +### 2.2 Check optional files + +**OPTIONAL** (enhance presentation - warn if missing but continue): +- ⚠️ `docs/project/api_spec.md` (for backend projects) +- ⚠️ `docs/project/database_schema.md` (for projects with database) +- ⚠️ `docs/project/design_guidelines.md` (for frontend projects) +- ⚠️ `docs/project/runbook.md` (for operational projects) + +For each optional file: +1. Use Glob tool: `pattern: "docs/project/{filename}"` +2. If NOT found: + - Add to optional missing list + +**If optional files missing:** +``` +⚠ WARN: Optional files missing: [list] +Presentation will have reduced content in some tabs. +Continue execution. +``` + +### 2.3 Check optional directories + +**OPTIONAL directories:** +- `docs/reference/adrs/` - check if any ADR files exist (`adrs/*.md`) +- `docs/reference/guides/` - check if any guide files exist (`guides/*.md`) +- `docs/tasks/kanban_board.md` - check for Roadmap data + +For each directory: +1. Use Glob tool to find files +2. If empty/missing: + - Log: `ℹ Optional directory empty: {directory} - related tab will show placeholder` + +### 2.4 Report validation summary + +Log summary: +``` +✓ Source documentation validation completed: + Required files: + - ✅ requirements.md (found, 8.5 KB) + - ✅ architecture.md (found, 15.2 KB) + - ✅ tech_stack.md (found, 3.1 KB) + Optional files: + - ⚠️ api_spec.md (missing - Technical Spec tab will have reduced content) + - ✅ database_schema.md (found, 4.7 KB) + - ⚠️ design_guidelines.md (missing) + Optional directories: + - ✅ adrs/ (5 ADR files found) + - ⚠️ guides/ (empty - Guides tab will show placeholder) + - ✅ kanban_board.md (found - Roadmap will show progress) +``` + +**Output**: Validation passed (all required files exist) OR error (stop execution) + +--- + +## Phase 3: Validate Source Content Quality + +**Objective**: Verify that source docs contain sufficient content for presentation generation. Warn about incomplete content but don't block execution. + +**When to execute**: After Phase 2 (source files exist) + +**Process**: + +### 3.1 Check for Mermaid diagrams + +**Required diagrams:** +- `architecture.md` MUST have at least 1 Mermaid diagram (preferably C4 Context) +- `database_schema.md` (if exists) MUST have ER diagram + +For each file: +1. Read file content +2. Search for Mermaid code blocks: ` ```mermaid` +3. Count diagrams + +**If diagrams missing:** +``` +⚠ WARN: Missing diagrams in architecture.md + Expected: At least 1 Mermaid diagram (C4 Context, Container, or Component) + Found: 0 diagrams + + Presentation Architecture tab will have incomplete visualization. + Suggestion: Add C4 diagrams to architecture.md before building. +``` + +### 3.2 Check for placeholders + +**Placeholder patterns to detect:** +- `{{PLACEHOLDER}}` (template placeholder) +- `[Add your ...]` (instruction placeholder) +- `TODO:` (incomplete content marker) + +For each source file: +1. Read file content +2. Search for placeholder patterns (case-insensitive) +3. Collect matches with line numbers + +**If placeholders found:** +``` +⚠ WARN: Source docs contain placeholders: + - requirements.md:42 - {{PROJECT_DESCRIPTION}} + - tech_stack.md:15 - [Add your technology rationale] + - api_spec.md:8 - TODO: Add authentication endpoints + + Presentation will show incomplete content. + Suggestion: Complete placeholders before building for professional result. +``` + +### 3.3 Check content length + +**Minimum expected lengths:** +- `requirements.md` > 500 words +- `architecture.md` > 1000 words +- `tech_stack.md` > 200 words + +For each file: +1. Read file content +2. Count words (split by whitespace, exclude code blocks) +3. Compare to threshold + +**If content too short:** +``` +⚠ WARN: Sparse content detected: + - requirements.md: 320 words (expected >500) + - tech_stack.md: 150 words (expected >200) + + Presentation may look incomplete with thin content. + Suggestion: Expand documentation before building. +``` + +### 3.4 Auto-fix opportunities + +**None** - ln-115 is **read-only** for source docs: +- ❌ Does NOT edit markdown documentation +- ✅ Only READS and TRANSFORMS to HTML + +**If issues found:** +``` +💡 To fix content issues: + - Run ln-114-project-docs-creator to complete documentation + - Manually edit source files in docs/project/ + - Re-run ln-115-presentation-creator after fixes +``` + +### 3.5 Report content quality summary + +Log summary: +``` +✓ Content quality validation completed: + Diagrams: + - ✅ architecture.md: 3 Mermaid diagrams found (C4 Context, Container, Component) + - ⚠️ database_schema.md: No ER diagram found + Placeholders: + - ⚠️ Found 2 placeholders in 2 files (see details above) + Content length: + - ✅ requirements.md: 1,250 words + - ✅ architecture.md: 2,100 words + - ⚠️ tech_stack.md: 180 words (expected >200) + + Warnings: 3 (non-blocking) + Recommendation: Address warnings for professional result, or continue with current content. +``` + +**Output**: Content quality report (warnings only, does not block execution) + +--- + +## Phase 4: Create Presentation Directory & README + +**Objective**: Setup presentation directory structure and navigation hub. + +**When to execute**: After Phase 3 (source validation complete, warnings logged) + +**Process**: + +1. **Create presentation directory**: + ```bash + mkdir -p docs/presentation/ + ``` + +2. **Check if presentation/README.md exists**: + - Use Glob tool: `pattern: "docs/presentation/README.md"` + - If file exists: + - Skip creation + - Log: `✓ docs/presentation/README.md already exists (preserved)` + - Proceed to Phase 5 + - If NOT exists: + - Continue to step 3 + +3. **Create presentation/README.md from template**: + - Copy template: `references/presentation_readme_template.md` → `docs/presentation/README.md` + - Replace placeholders: + - `{{PROJECT_NAME}}` — from requirements.md + - `{{LAST_UPDATED}}` — current date (YYYY-MM-DD) + - Content structure: + - **Purpose**: What is this presentation + - **Quick Navigation**: Links to presentation_final.html and assets/ + - **Customization Guide**: How to edit source files in assets/ + - **Build Instructions**: How to rebuild after changes + - **Maintenance**: When to rebuild, verification checklist + +4. **Notify user**: + - If created: `✓ Created docs/presentation/README.md (navigation hub)` + - If skipped: `✓ docs/presentation/README.md already exists (preserved)` + +**Output**: docs/presentation/README.md (created or existing) + +--- + +## Phase 5: Copy Templates to Project + +**Objective**: Copy HTML/CSS/JS templates from skill references/ to presentation directory. + +**When to execute**: After Phase 4 (presentation directory exists) + +**Process**: + +1. **Check if assets exist**: + - Use Glob tool: `pattern: "docs/presentation/assets/"` + - If `docs/presentation/assets/` exists: + - Skip copying (user may have customized files) + - Log: `✓ Presentation assets already exist - preserving user customizations` + - Proceed to Phase 6 + - If NOT exists: + - Continue to step 2 + +2. **Copy template files**: + ```bash + cp references/presentation_template.html → docs/presentation/assets/ + cp references/styles.css → docs/presentation/assets/ + cp references/scripts.js → docs/presentation/assets/ + cp references/build-presentation.js → docs/presentation/assets/ + cp -r references/tabs/ → docs/presentation/assets/tabs/ + ``` + +3. **Verify copied structure**: + ``` + docs/presentation/assets/ + ├── presentation_template.html # Base HTML5 + 6 tab navigation + ├── styles.css # ~400-500 lines + ├── scripts.js # Tab switching + Mermaid init + ├── build-presentation.js # Node.js build script + └── tabs/ + ├── tab_overview.html # Landing page + ├── tab_requirements.html # FRs + ADRs + ├── tab_architecture.html # C4 diagrams + ├── tab_technical_spec.html # API + Data + Deployment + ├── tab_roadmap.html # Epic list + └── tab_guides.html # How-to guides + ``` + +**Output**: Template files copied to docs/presentation/assets/ (or skipped if already exist) + +**Note**: Templates contain placeholders (`{{VARIABLE_NAME}}`) that will be replaced in Phase 6. + +--- + +## Phase 6: Content Injection & Example Cleanup + +**Objective**: Parse MD documentation, inject into HTML templates, and remove example blocks to create project-specific presentation. + +**When to execute**: After Phase 5 (templates exist in assets/) + +**Process**: + +### 6.1 Read and Parse MD Documents + +Read and parse the following documentation files (from Phase 1): + +1. **requirements.md**: Project name, tagline, business goal, functional requirements, constraints, success criteria +2. **architecture.md**: Architecture diagrams (C4 Context/Container/Component), solution strategy, quality attributes +3. **tech_stack.md**: Technology Stack table (with versions, rationale, ADR links), Docker configuration +4. **api_spec.md** (if exists): API endpoints, authentication methods, error codes +5. **database_schema.md** (if exists): ER diagrams, data dictionary (tables/columns/types) +6. **design_guidelines.md** (if exists): Typography, colors, component library, accessibility +7. **runbook.md** (if exists): Development setup, deployment procedures, troubleshooting +8. **adrs/*.md**: All ADR files (parse title, status, category, content) +9. **kanban_board.md** (if exists): Epic Story Counters table for Roadmap progress +10. **guides/*.md** (if exist): How-to guides for Guides tab + +### 6.2 Inject Content into Templates + +Replace placeholders in copied template files with parsed content from project documentation. + +**Key Placeholders (in tab templates):** + +**Overview Tab** (`tab_overview.html`): +- `{{PROJECT_SUMMARY}}` — Problem/Solution/Business Value structure (3 sections) +- `{{TECH_STACK}}` — Technology badges (brief list only) +- `{{STAKEHOLDERS}}` — Stakeholder cards with names and roles +- `{{QUICK_FACTS}}` — Project Status, Total Epics, Deployment Model, Target Platforms +- `{{NAVIGATION_GUIDE}}` — Documentation guide with tab descriptions + +**Requirements Tab** (`tab_requirements.html`): +- `{{FUNCTIONAL_REQUIREMENTS}}` — FRs table (ID, Priority, Requirement, Acceptance Criteria) +- `{{ADR_STRATEGIC}}` — Strategic ADRs grouped section with accordion +- `{{ADR_TECHNICAL}}` — Technical ADRs grouped section with accordion +- `{{SUCCESS_CRITERIA}}` — Project success metrics +- **Non-Functional Requirements are banned**: Drop any NFR content found in source docs instead of converting it into tables or IDs + +**Architecture Tab** (`tab_architecture.html`): +- `{{C4_CONTEXT}}` — System Context diagram (C4 Level 1) +- `{{C4_CONTAINER}}` — Container diagram (C4 Level 2) +- `{{C4_COMPONENT}}` — Component diagram (C4 Level 3) +- `{{DEPLOYMENT_DIAGRAM}}` — Infrastructure deployment diagram +- `{{ARCHITECTURE_NOTES}}` — Key architecture highlights table + +**Technical Spec Tab** (`tab_technical_spec.html`): +- `{{TECH_STACK_TABLE}}` — Full technology stack table with versions and purposes +- `{{API_ENDPOINTS}}` — API endpoints tables (Authentication, Products, Cart, etc.) +- `{{DATA_MODELS}}` — ER diagram + Data dictionary table +- `{{TESTING_STRATEGY}}` — Risk-Based Testing approach and test pyramid + +**Roadmap Tab** (`tab_roadmap.html`): +- `{{EPIC_CARDS}}` — All Epic cards with In/Out Scope, Dependencies, Success Criteria, Progress +- `{{OUT_OF_SCOPE_ITEMS}}` — Project-level out-of-scope items with reasons +- `{{ROADMAP_LEGEND}}` — Status badges explanation + +**Guides Tab** (`tab_guides.html`): +- `{{GETTING_STARTED}}` — Prerequisites, Installation, Verification +- `{{HOW_TO_GUIDES}}` — Step-by-step how-to guides (from guides/*.md) +- `{{BEST_PRACTICES}}` — Code style, Testing approach, Design patterns +- `{{TROUBLESHOOTING}}` — Common problems and solutions +- `{{CONTRIBUTING}}` — Contributing guidelines +- `{{EXTERNAL_RESOURCES}}` — Links to external documentation + +**Placeholder Replacement Logic:** +- Use **Edit** tool to replace `{{PLACEHOLDER}}` → actual content from project docs +- For lists/arrays: generate HTML dynamically (e.g., loop through ADRs, create `
` elements) +- For Kanban: parse kanban_board.md → calculate progress % → generate Epic card HTML +- Preserve SCOPE tags in tab files (HTML comments at top) +- Escape special characters to prevent XSS +- Generate valid Mermaid syntax + +### 6.3 Delete Example Blocks + +**CRITICAL**: Remove all example content blocks to create project-specific presentation. + +**Process**: +1. **Search for example markers** in all 6 tab files: + - Look for `` + - Look for `` + +2. **Delete example blocks** using Edit tool: + - Remove everything between `` and `` (inclusive) + - Do this for ALL occurrences across all 6 tab files + - Leave only the actual project content that replaced `{{PLACEHOLDER}}` comments + +3. **Validate cleanup**: + - ✅ NO `` markers should remain + - ✅ NO `` markers should remain + - ✅ NO hardcoded e-commerce examples (John Smith, React 18 badges, Stripe, etc.) + - ✅ Only actual project data should be visible in tab files + +**Example transformation:** + +**Before (dual-content template):** +```html + + +
+

The Problem

+

Traditional e-commerce platforms struggle...

+
+ +``` + +**After Step 6.2 (placeholder replaced):** +```html +
+

The Problem

+

Our healthcare system needs unified patient records...

+
+ +
+

The Problem

+

Traditional e-commerce platforms struggle...

+
+ +``` + +**After Step 6.3 (examples deleted):** +```html +
+

The Problem

+

Our healthcare system needs unified patient records...

+
+``` + +**Output**: Clean, project-specific tab files with NO example content, ready for build + +--- + +## Phase 7: Build Final Presentation + +**Objective**: Assemble modular components into standalone HTML file. + +**When to execute**: After Phase 6 (content injected, examples deleted) + +**Process**: + +1. **Check if presentation_final.html exists (Auto-rebuild for automation)**: + - Use Glob tool: `pattern: "docs/presentation/presentation_final.html"` + - If file exists: + - **✓ Auto-rebuild** (generated file, safe operation) + - Log: `ℹ Rebuilding presentation_final.html (generated file, safe to rebuild)` + - Continue to step 2 + - If NOT exists: + - Log: `Creating presentation_final.html` + - Continue to step 2 + + **Why auto-rebuild:** + - presentation_final.html is a **generated file** (source of truth: assets/ directory) + - Rebuilding is safe - no data loss (source files preserved in assets/) + - Maintains fully automatic workflow when invoked by ln-110-documents-pipeline + - User customizations in assets/ are preserved (only final HTML is regenerated) + +2. **Navigate to presentation assets directory**: + ```bash + cd docs/presentation/assets/ + ``` + +3. **Run build script**: + ```bash + node build-presentation.js + ``` + +4. **Build Script Process**: + - **Step 1**: Read presentation_template.html + - **Step 2**: Read and inline styles.css → ` + + +
+ +
+

E-Commerce Platform

+

Modern Online Shopping Solution

+
+ + + + + +
+
+ + + + +
+

Project Summary

+ +

The Problem

+

Traditional e-commerce platforms struggle with scalability during peak traffic, complex payment integrations, and fragmented inventory management across multiple channels. Businesses need a unified platform that handles high concurrent loads while maintaining data consistency and security.

+ +

Our Solution

+

An enterprise-grade e-commerce platform built with modern web technologies and modular architecture. The system provides seamless online shopping experiences through stateless API design, robust payment processing with PCI DSS compliance, real-time inventory synchronization, and comprehensive customer analytics.

+ +

Business Value

+
    +
  • Scalability: Support 10,000+ concurrent users with horizontal scaling
    • +
  • Reliability: 99.9% uptime SLA with automated failover
    • +
  • Speed to Market: Modular architecture enables rapid feature delivery
    • +
  • Cost Efficiency: Optimized infrastructure reduces operational costs by 30%
    • +
+
+ +
+

Technology Stack

+
+ React 18 + Node.js + PostgreSQL + Redis + Docker + TypeScript +
+
+ +
+

Key Stakeholders

+
+
+

Project Owner

+

John Smith

+

Business Sponsor

+
+
+

Lead Architect

+

Jane Doe

+

Technical Lead

+
+
+

Development Lead

+

Alex Johnson

+

Engineering Manager

+
+
+

Product Manager

+

Sarah Williams

+

Product Strategy

+
+
+
+ +
+

Project Quick Facts

+
+
+

In Progress

+

Project Status

+
+
+

7

+

Total Epics

+
+
+

Cloud

+

Deployment Model

+
+
+

Web + Mobile

+

Target Platforms

+
+
+
+ +
+

Documentation Guide

+
+
+

📋 Requirements

+

What we're building and why - functional requirements only and architecture decisions (ADRs); Non-Functional Requirements are not produced

+

For: Product Owners, Business Analysts, Architects

+
+
+

🏗️ Architecture

+

How the system is designed - C4 diagrams showing context, containers, components, and deployment infrastructure

+

For: Architects, Technical Leads, DevOps Engineers

+
+
+

⚙️ Technical Spec

+

How to interact with the system - API documentation, data models, schemas, and infrastructure configuration

+

For: Developers, QA Engineers, Integration Teams

+
+
+

🗺️ Roadmap

+

Work order and scope boundaries - Kanban board showing epic progress, dependencies, and what's in/out of scope

+

For: Stakeholders, Project Managers, Executives

+
+
+

📚 Guides

+

How to perform practical tasks - step-by-step guides for installation, development, deployment, and integration

+

For: Developers, DevOps Engineers, New Team Members

+
+
+
+ +
+ +
+ + + + +

Requirements

+ +
+

Functional Requirements

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDPriorityRequirementAcceptance Criteria
FR-AUTH-001MUSTUser Registration and Login
+ Users must be able to register with email/password and login to access personalized features		 +
    +
  • Email validation (RFC 5322 compliant)
    • +
  • Password strength requirements (min 8 chars, uppercase, lowercase, number)
    • +
  • JWT token-based authentication
    • +
+
FR-CATALOG-001MUSTProduct Catalog Display
+ System must display product catalog with search, filters, and pagination		 +
    +
  • Full-text search across product names and descriptions
    • +
  • Filter by category, price range, availability
    • +
  • Paginate results (20 items per page)
    • +
+
FR-CART-001MUSTShopping Cart Management
+ Users must be able to add/remove products to/from cart		 +
    +
  • Add product with quantity selection
    • +
  • Update quantities in cart
    • +
  • Remove items from cart
    • +
  • Cart persists across sessions (logged-in users)
    • +
+
+
+ +
+

Non-Functional Requirements (forbidden)

+ +

Not generated: project policy forbids formal Non-Functional Requirements. Capture quality-related decisions only in architecture narratives, not as requirement tables.

+
+ +
+

📋 Architecture Decision Records

+ +
+

🎯 Strategic Decisions

+ +
+ ADR-001: Microservices vs Monolith Architecture +

Date: 2025-09-15 | Status: Accepted | Category: Strategic

+ +

Context

+

Need to choose architecture pattern for e-commerce platform considering team size, scaling requirements, and deployment complexity.

+ +

Decision

+

Use modular monolith architecture with clear domain boundaries.

+ +

Rationale

+
    +
  • Small team (5 developers) - microservices overhead too high
    • +
  • Faster time to market with simplified deployment
    • +
  • Clear module boundaries allow future microservices extraction
    • +
+ +

Alternatives Considered

+ + + + + + + + + + + + + + + + + + + + + + + +
AlternativeProsConsRejection Reason
MicroservicesIndependent scaling, technology diversityOperational complexity, team overheadTeam too small, premature optimization
Traditional monolithSimplest to buildDifficult to scale, tight couplingNo clear boundaries for future evolution
+ +

Consequences

+

Positive:

+
    +
  • Faster development and deployment
    • +
  • Easier testing and debugging
    • +
  • Lower infrastructure costs
    • +
+

Negative:

+
    +
  • Cannot scale individual modules independently
    • +
  • Requires discipline to maintain module boundaries
    • +
+
+
+ +
+

🔧 Technical Decisions

+ +
+ ADR-002: Database Choice - PostgreSQL vs MongoDB +

Date: 2025-09-18 | Status: Accepted | Category: Technical

+ +

Context

+

Need to select database for e-commerce transactional data considering ACID requirements, scalability, and query complexity.

+ +

Decision

+

Use PostgreSQL 15.x as primary database.

+ +

Rationale

+
    +
  • Strong ACID guarantees for transactions (orders, payments)
    • +
  • JSON support for flexible product attributes
    • +
  • Excellent performance for complex queries
    • +
+ +

Alternatives Considered

+ + + + + + + + + + + + + + + + + + + + + + + +
AlternativeProsConsRejection Reason
MongoDBSchema flexibility, horizontal scalingWeak transaction support, complex queries difficultE-commerce requires strong ACID for financial data
MySQLWidely adopted, good performanceLimited JSON support, fewer featuresPostgreSQL offers better feature set
+ +

Consequences

+

Positive:

+
    +
  • Data integrity guaranteed for financial transactions
    • +
  • Rich ecosystem and tooling
    • +
+

Negative:

+
    +
  • Vertical scaling limitations (mitigated by read replicas)
    • +
  • Schema migrations require careful planning
    • +
+
+
+
+ +
+

Success Criteria

+
    +
  • ✅ MVP handles 1,000+ daily active users
    • +
  • ✅ 99.5% uptime in first 3 months
    • +
  • ✅ Average checkout time < 3 minutes
    • +
  • ✅ 85%+ test coverage (E2E + Integration + Unit)
    • +
  • ✅ Zero critical security vulnerabilities
    • +
+
+ +
+ +
+ + + + +

Architecture

+ +
+

System Context (C4 Level 1)

+

High-level view of the e-commerce platform and its external dependencies.

+
+graph TD + Customer[Customer] + Admin[Administrator] + PaymentGateway[Payment Gateway
Stripe] + EmailService[Email Service
SendGrid] + + System[E-Commerce Platform] + + Customer -->|Browse products,
Place orders| System + Admin -->|Manage products,
View analytics| System + System -->|Process payments| PaymentGateway + System -->|Send notifications| EmailService +
+ +

Container Diagram (C4 Level 2)

+

Containers within the e-commerce platform showing technologies and communication.

+
+graph TD + Customer[Customer
Web Browser] + Admin[Administrator
Web Browser] + + WebApp[Web Application
React 18 SPA] + API[REST API
Node.js + Express] + Database[(Database
PostgreSQL 15)] + Cache[(Cache
Redis)] + + Customer -->|HTTPS| WebApp + Admin -->|HTTPS| WebApp + WebApp -->|JSON/HTTPS| API + API -->|SQL| Database + API -->|Cache queries| Cache +
+ +

Component Diagram (C4 Level 3) - Optional for Technical Audiences

+

Components within the REST API container showing internal structure.

+
+graph TD + API[REST API Container] + + AuthController[Authentication
Controller] + ProductController[Product Catalog
Controller] + CartController[Shopping Cart
Controller] + OrderController[Order
Controller] + + AuthService[Auth Service] + ProductService[Product Service] + CartService[Cart Service] + OrderService[Order Service] + + ProductRepo[Product
Repository] + UserRepo[User
Repository] + CartRepo[Cart
Repository] + OrderRepo[Order
Repository] + + Database[(PostgreSQL)] + Cache[(Redis)] + + ProductController --> ProductService + CartController --> CartService + OrderController --> OrderService + AuthController --> AuthService + + ProductService --> ProductRepo + CartService --> CartRepo + OrderService --> OrderRepo + AuthService --> UserRepo + + ProductRepo --> Database + UserRepo --> Database + CartRepo --> Cache + OrderRepo --> Database +
+ +

Deployment Diagram

+

Infrastructure and deployment architecture on AWS.

+
+graph TD + subgraph "AWS Cloud" + subgraph "Public Subnet" + ALB[Application Load
Balancer] + CloudFront[CloudFront CDN] + end + + subgraph "Private Subnet" + ECS1[ECS Container 1
Node.js API] + ECS2[ECS Container 2
Node.js API] + + RDS[(RDS PostgreSQL
Primary)] + RDSReplica[(RDS PostgreSQL
Read Replica)] + + ElastiCache[(ElastiCache
Redis)] + end + + subgraph "Storage" + S3[S3 Bucket
Static Assets] + end + end + + CloudFront --> S3 + ALB --> ECS1 + ALB --> ECS2 + ECS1 --> RDS + ECS2 --> RDS + ECS1 --> RDSReplica + ECS2 --> RDSReplica + ECS1 --> ElastiCache + ECS2 --> ElastiCache +
+
+ +
+

Key Architecture Highlights

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AspectApproachRationale
Architecture PatternModular MonolithClear domain boundaries (Auth, Catalog, Cart, Orders) - see ADR-001 in Requirements
API DesignStateless APIEnables horizontal scaling without session affinity
Database StrategyPostgreSQL with read replicasACID transactions + scalability through read replicas
CachingRedisSession/cart data and frequently accessed product catalog
InfrastructureDocker containersCloud-native orchestration with Kubernetes
+ +

Quality attributes (Performance, Security, Scalability, Maintainability) are described in architecture narratives; formal Non-Functional Requirements are intentionally excluded.

+
+ +
+ +
+ + + + +

Technical Specification

+ +
+

Technology Stack

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryTechnologyVersionPurpose
FrontendReact18.2UI framework for SPA
FrontendTypeScript5.2Type-safe JavaScript
BackendNode.js20.xRuntime environment
BackendExpress4.18REST API framework
DatabasePostgreSQL15.xPrimary transactional database
CacheRedis7.xSession & cart caching
InfrastructureDocker24.xContainerization
InfrastructureAWS ECS-Container orchestration
DevOpsGitHub Actions-CI/CD pipeline
+
+ +
+

API Endpoints

+ +

Authentication

+ + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodDescription
/api/auth/registerPOSTRegister new user
/api/auth/loginPOSTLogin and get JWT token
/api/auth/refreshPOSTRefresh JWT token
+ +

Products

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodDescription
/api/productsGETList all products (paginated)
/api/products/:idGETGet product details
/api/productsPOSTCreate new product (admin only)
/api/products/:idPUTUpdate product (admin only)
+ +

Shopping Cart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodDescription
/api/cartGETGet current user's cart
/api/cart/itemsPOSTAdd item to cart
/api/cart/items/:idPUTUpdate item quantity
/api/cart/items/:idDELETERemove item from cart
+ +

Authentication

+

Method: JWT Bearer Token

+ 
Authorization: Bearer <token>
+

Token expires in 15 minutes. Use /api/auth/refresh with refresh token to get new access token.

+ +

Error Codes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeMessageDescription
400Bad RequestInvalid request payload
401UnauthorizedMissing or invalid JWT token
403ForbiddenInsufficient permissions
404Not FoundResource not found
500Internal Server ErrorUnexpected server error
+
+ +
+

Data Models

+ +

Entity Relationship Diagram

+
+erDiagram + USER ||--o{ ORDER : places + USER ||--o{ CART : has + CART ||--|{ CART_ITEM : contains + PRODUCT ||--o{ CART_ITEM : "in" + PRODUCT ||--o{ ORDER_ITEM : "in" + ORDER ||--|{ ORDER_ITEM : contains + ORDER ||--|| PAYMENT : has + + USER { + uuid id PK + string email + string password_hash + string first_name + string last_name + timestamp created_at + } + + PRODUCT { + uuid id PK + string name + text description + decimal price + int stock_quantity + string category + timestamp created_at + } + + CART { + uuid id PK + uuid user_id FK + timestamp updated_at + } + + CART_ITEM { + uuid id PK + uuid cart_id FK + uuid product_id FK + int quantity + } + + ORDER { + uuid id PK + uuid user_id FK + decimal total_amount + string status + timestamp created_at + } + + ORDER_ITEM { + uuid id PK + uuid order_id FK + uuid product_id FK + int quantity + decimal price_at_purchase + } + + PAYMENT { + uuid id PK + uuid order_id FK + string payment_method + string status + string transaction_id + timestamp created_at + } +
+ +

Data Dictionary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EntityKey AttributesDescription
USERemail (unique), password_hashCustomer accounts
PRODUCTname, price, stock_quantityProduct catalog items
CARTuser_idShopping cart (1 per user)
ORDERuser_id, status, total_amountCustomer orders
PAYMENTorder_id, transaction_id, statusPayment transactions
+
+ +
+

Testing Strategy

+

Risk-Based Testing approach - prioritize tests by business impact:

+ +

Test Pyramid

+
    +
  • E2E Tests (2-5 per Story): Critical user flows (checkout, payment, registration)
    • +
  • Integration Tests (3-8 per Story): API endpoints, database interactions
    • +
  • Unit Tests (5-15 per Story): Business logic, validators, utilities
    • +
+ +

Total: 10-28 tests per Story (max)

+ +

Priority Matrix

+

Test scenarios with Priority ≥ 15 MUST be tested:

+ 
Priority = Business Impact (1-5) × Probability (1-5)
+ +

Test Focus

+
    +
  • ✅ Test OUR code (business logic, API endpoints)
    • +
  • ❌ Skip framework code (Express middleware already tested)
    • +
  • ❌ Skip trivial getters/setters (no business logic)
    • +
+
+ +
+ +
+ + + + +

Roadmap

+ +

This roadmap shows the work order and scope boundaries for our project. Epics are organized by dependencies, with clear scope definition for each.

+ +
+ +
+
+

Epic 1: User Management

+ Done +
+

User registration, authentication, profile management, and session handling

+ +
+
+

In Scope

+
    +
  • JWT authentication
    • +
  • Email/password registration
    • +
  • Password reset flow
    • +
  • User profile CRUD operations
    • +
  • Session management
    • +
+
+
+

Out of Scope

+
    +
  • Social login (OAuth)
    • +
  • Multi-factor authentication
    • +
  • Single sign-on (SSO)
    • +
+
+
+ +
+

Dependencies: None (Foundation epic)

+

Success Criteria: JWT authentication, < 2s login time, Password reset flow

+

Progress: 6/6 stories completed (100%)

+
+
+ + +
+
+

Epic 2: Product Catalog

+ Done +
+

Product listing, search, filters, and pagination

+ +
+
+

In Scope

+
    +
  • Full-text search across product names and descriptions
    • +
  • Category filters
    • +
  • Price range filters
    • +
  • Pagination (20 items/page)
    • +
  • Product detail pages
    • +
  • 1000+ SKUs support
    • +
+
+
+

Out of Scope

+
    +
  • AI-powered recommendations
    • +
  • Visual search
    • +
  • Product reviews
    • +
+
+
+ +
+

Dependencies: Epic 1 (User Management for admin features)

+

Success Criteria: Full-text search, 1000+ SKUs, < 1s search response

+

Progress: 8/8 stories completed (100%)

+
+
+ + +
+
+

Epic 3: Shopping Cart

+ In Progress +
+

Cart management with session persistence and inventory validation

+ +
+
+

In Scope

+
    +
  • Add/remove items from cart
    • +
  • Update quantities
    • +
  • Cart persistence across sessions
    • +
  • Real-time inventory validation
    • +
  • Cart subtotal calculation
    • +
+
+
+

Out of Scope

+
    +
  • Wishlist functionality
    • +
  • Share cart
    • +
  • Save for later
    • +
+
+
+ +
+

Dependencies: Epic 2 (Product Catalog)

+

Success Criteria: Cart persists across sessions, real-time inventory sync, < 500ms cart operations

+

Progress: 3/8 stories completed (37%)

+
+
+ + +
+
+

Epic 4: Admin Dashboard

+ In Progress +
+

Product management, inventory control, and analytics dashboard

+ +
+
+

In Scope

+
    +
  • Product CRUD operations
    • +
  • Bulk product import (CSV)
    • +
  • Inventory management
    • +
  • Role-based access control
    • +
  • Real-time analytics dashboard
    • +
  • Sales reports
    • +
+
+
+

Out of Scope

+
    +
  • Customer support tickets
    • +
  • Email campaigns
    • +
  • Advanced BI reports
    • +
+
+
+ +
+

Dependencies: Epic 1 (User Management), Epic 2 (Product Catalog)

+

Success Criteria: Role-based access control, bulk product import, real-time analytics

+

Progress: 2/7 stories completed (28%)

+
+
+ + +
+
+

Epic 5: Payment Gateway

+ Todo +
+

Integrate Stripe for secure payment processing with PCI DSS compliance

+ +
+
+

In Scope

+
    +
  • Stripe payment integration
    • +
  • Credit/debit card payments
    • +
  • Digital wallets (Apple Pay, Google Pay)
    • +
  • PCI DSS compliance
    • +
  • Payment error handling
    • +
  • Refund processing
    • +
+
+
+

Out of Scope

+
    +
  • Cryptocurrency payments
    • +
  • Buy now, pay later (BNPL)
    • +
  • Invoice payments
    • +
+
+
+ +
+

Dependencies: Epic 3 (Shopping Cart)

+

Success Criteria: PCI DSS compliant, < 3s checkout time, support 5+ payment methods

+

Progress: 0/5 stories planned

+
+
+ + +
+
+

Epic 6: Order Management

+ Todo +
+

Order processing, tracking, and fulfillment workflows

+ +
+
+

In Scope

+
    +
  • Order creation and confirmation
    • +
  • Real-time order tracking
    • +
  • Email notifications
    • +
  • Order history
    • +
  • Automated fulfillment workflows
    • +
  • Cancellation and refund flows
    • +
+
+
+

Out of Scope

+
    +
  • Advanced shipping integrations
    • +
  • Returns management portal
    • +
  • International shipping
    • +
+
+
+ +
+

Dependencies: Epic 5 (Payment Gateway)

+

Success Criteria: Real-time order tracking, automated fulfillment notifications, < 1min order confirmation

+

Progress: 0/6 stories planned

+
+
+ + +
+
+

Epic 7: Advanced Analytics

+ Backlog +
+

Customer behavior analytics and recommendations engine

+ +
+
+

In Scope

+
    +
  • Customer behavior tracking
    • +
  • Product recommendations engine
    • +
  • Conversion funnel analytics
    • +
  • A/B testing framework
    • +
  • Personalized user experience
    • +
+
+
+

Out of Scope

+
    +
  • Machine learning models
    • +
  • Predictive analytics
    • +
  • Customer data platform (CDP)
    • +
+
+
+ +
+

Dependencies: Epic 2 (Product Catalog), Epic 6 (Order Management)

+

Success Criteria: 15% increase in conversion rate, personalized recommendations for 80%+ users

+

Progress: 0/9 stories planned

+
+
+
+ +
+

Out of Project Scope

+

The following items are explicitly NOT included in the current project phase:

+ +
+
+

Mobile Native Apps

+

iOS and Android native applications

+

Reason: Focus on responsive web first, native apps planned for Phase 2

+
+ +
+

Multi-Currency Support

+

International payments and currency conversion

+

Reason: Current scope limited to USD, internationalization in future release

+
+ +
+

Social Commerce Integration

+

Social media selling and live shopping features

+

Reason: Not in MVP scope, evaluate after core features stable

+
+ +
+

B2B Wholesale Portal

+

Bulk ordering and wholesale pricing for business customers

+

Reason: B2C focus first, B2B features separate project phase

+
+
+
+ +
+

Status Legend

+
+ Done Completed and deployed + In Progress Currently being developed + Todo Approved and ready to start + Backlog Under evaluation +
+
+ +
+ +
+ + + + +

Guides & Resources

+ +
+

Getting Started

+ +

Prerequisites

+
    +
  • Node.js 20.x or higher
    • +
  • PostgreSQL 15.x
    • +
  • Redis 7.x (optional for development)
    • +
  • Docker (optional)
    • +
+ +

Installation

+ 
git clone https://github.com/example/ecommerce-platform.git
+cd ecommerce-platform
+npm install
+cp .env.example .env
+# Edit .env with your database credentials
+npm run db:migrate
+npm run dev
+ +

Verification

+

After starting the server, verify installation:

+
    +
  • ✅ Server running at http://localhost:3000
    • +
  • ✅ API health check: curl http://localhost:3000/api/health
    • +
  • ✅ Database migrations applied: npm run db:status
    • +
+
+ +
+

How-To Guides

+ +
+

How to Add a New Product

+
    +
  1. Login as admin: POST /api/auth/login with admin credentials
    2. +
  2. Get JWT token from response
    3. +
  3. Create product: + 
    curl -X POST http://localhost:3000/api/products \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Product Name",
+    "description": "Product Description",
+    "price": 29.99,
+    "stock_quantity": 100,
+    "category": "Electronics"
+  }'
    +
    4. +
  4. Verify product created: GET /api/products/:id
    5. +
+
+ +
+

How to Test API Endpoints

+
    +
  1. Start development server: npm run dev
    2. +
  2. Run tests: +
      +
    • All tests: npm test
      • +
    • E2E tests only: npm run test:e2e
      • +
    • Integration tests: npm run test:integration
      • +
    • Unit tests: npm run test:unit
      • +
    +
    3. +
  3. View coverage report: npm run test:coverage
    4. +
+
+ +
+

How to Deploy to Production

+
    +
  1. Build Docker image: docker build -t ecommerce-api .
    2. +
  2. Push to registry: docker push ecommerce-api:latest
    3. +
  3. Update ECS task definition with new image
    4. +
  4. Deploy via GitHub Actions (automatic on merge to main)
    5. +
  5. Verify deployment: Check CloudWatch logs for startup
    6. +
+
+
+ +
+

Best Practices

+ +

Code Style

+
    +
  • Follow KISS/YAGNI/DRY principles
    • +
  • Use TypeScript for type safety
    • +
  • Keep functions small and focused (< 30 lines)
    • +
  • Use meaningful variable names (no single letters except loops)
    • +
+ +

Testing Approach

+
    +
  • Follow Risk-Based Testing (Priority ≥ 15 scenarios MUST be tested)
    • +
  • E2E tests (2-5 per Story): Critical user flows
    • +
  • Integration tests (3-8 per Story): API endpoints
    • +
  • Unit tests (5-15 per Story): Business logic only
    • +
  • Test OUR code, not frameworks (Express already tested)
    • +
+ +

Design Patterns

+
    +
  • Layered architecture: Controller → Service → Repository
    • +
  • Dependency Injection for testability
    • +
  • Repository pattern for database access
    • +
  • DTO (Data Transfer Objects) for API requests/responses
    • +
+
+ +
+

Troubleshooting

+ +

Database Connection Errors

+

Problem: "Unable to connect to PostgreSQL"

+

Solution:

+
    +
  • Check PostgreSQL is running: pg_isready
    • +
  • Verify .env credentials match database
    • +
  • Check firewall allows port 5432
    • +
+ +

Port Already in Use

+

Problem: "Port 3000 is already in use"

+

Solution:

+
    +
  • Change PORT in .env to different port (e.g., 3001)
    • +
  • Or kill process using port: lsof -ti:3000 | xargs kill
    • +
+ +

JWT Token Expired

+

Problem: "401 Unauthorized - Token expired"

+

Solution:

+
    +
  • Use refresh token: POST /api/auth/refresh with refresh token
    • +
  • Get new access token from response
    • +
  • Tokens expire after 15 minutes for security
    • +
+ +

Tests Failing Randomly

+

Problem: Tests pass locally but fail in CI

+

Solution:

+
    +
  • Check test isolation (no shared state between tests)
    • +
  • Use transactions in tests (rollback after each test)
    • +
  • Seed database with consistent test data
    • +
+
+ +
+

Contributing Guidelines

+
    +
  1. Fork the repository
    2. +
  2. Create branch: git checkout -b feature/your-feature
    3. +
  3. Write code following style guide
    4. +
  4. Write tests: All new code must have tests (85%+ coverage)
    5. +
  5. Run tests: npm test (all must pass)
    6. +
  6. Commit: git commit -m "Add your feature"
    7. +
  7. Push: git push origin feature/your-feature
    8. +
  8. Submit PR with description of changes
    9. +
+
+ +
+

External Resources

+ +
+ +
+
+ + + +
+ + + + diff --git a/skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md b/skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md new file mode 100644 index 0000000..0046a9f --- /dev/null +++ b/skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md @@ -0,0 +1,302 @@ +# x-html-builder Template Architecture + +This document describes the structure and content specifications for all HTML templates used by x-html-builder skill. + +## File Structure + +All templates are stored in `x-html-builder/references/` following the Template Ownership Principle (each skill owns its templates): + +``` +x-html-builder/references/ +├── presentation_template.html # Base HTML5 structure with 6 tab navigation +├── styles.css # CSS Variables, responsive design (~500 lines) +├── scripts.js # Tab switching, collapsible sections, Mermaid init +├── build-presentation.js # Node.js build script for inlining +└── tabs/ + ├── tab_overview_template.html # Landing page + ├── tab_requirements_template.html # FRs + ADRs (Non-Functional Requirements are forbidden) + ├── tab_architecture_template.html # C4 diagrams + ├── tab_technical_spec_template.html # API + Data + Deployment + ├── tab_roadmap_template.html # Kanban-style + └── tab_guides_template.html # How-to guides +``` + +## Tab Content Specifications + +### Tab 1: Overview (Landing Page) + +**File:** `tab_overview_template.html` + +**SCOPE:** +- INCLUDES: Project name, tagline, business goal, tech stack badges, role-based navigation, quick stats, recent updates +- EXCLUDES: Full requirements → Requirements tab, Detailed diagrams → Architecture tab, Full roadmap → Roadmap tab, API details → Technical Spec tab + +**Content Elements:** +- **Header Intro:** Project name (h1) + tagline (minimal, no gradient background) +- **Project Summary:** Business goal in "About This Project" section (h2) +- **Role-Based Navigation:** 4 cards (Developer/Architect/Product Owner/Stakeholder) - clickable, switches to relevant tab +- **Tech Stack Badges:** Technology badges with icons and names +- **Quick Stats:** Project statistics grid (total epics, completed stories, test coverage, uptime SLA) +- **Recent Updates:** Recent project updates list +- **Quick Links:** Links to other tabs (Requirements, Architecture, API Reference, Roadmap) + +**Data Sources:** +- requirements.md (project name, business goal) +- architecture.md (tech stack) +- kanban_board.md (stats, recent updates) + +**Placeholders:** +- `{{PROJECT_NAME}}` - Project name from requirements.md ## Project Name +- `{{PROJECT_TAGLINE}}` - Short description from requirements.md +- `{{BUSINESS_GOAL}}` - Business goals section from requirements.md +- `{{TECH_STACK_BADGES}}` - Generated from architecture.md tech stack +- `{{QUICK_STATS}}` - Generated from kanban_board.md Epic Story Counters +- `{{RECENT_UPDATES}}` - Placeholder (currently undefined - TODO: specify data source) + +### Tab 2: Requirements + +**File:** `tab_requirements_template.html` + +**SCOPE:** +- INCLUDES: Business goals, FRs (collapsible), ADRs (Strategic/Technical groups), constraints, success criteria +- EXCLUDES: Implementation details → Technical Spec, Diagrams → Architecture, Code → Guides, Non-Functional Requirements (explicitly banned from this tab) + +**Content Elements:** +- **Business Goals:** Project objectives with key targets (h2 + list) +- **Functional Requirements:** Collapsible by domain (details/summary tags) - FR-XXX-001 format with Priority (MUST/SHOULD/COULD), Description +- **ADRs Section:** Grouped by category: + - **Strategic Decisions** (h3) - Business/architecture strategy ADRs + - **Technical Decisions** (h3) - Technology/implementation ADRs + - Each ADR in accordion (details/summary) with full content inline: + - Date | Status | Category (metadata line) + - Context (h4) + - Decision (h4) + - Rationale (h4 + list) + - Alternatives Considered (h4 + table: Alternative | Pros | Cons | Rejection Reason) + - Consequences (h4 + Positive/Negative lists) +- **Constraints:** Technology constraints +- **Success Criteria:** Measurable project success metrics + +**Data Sources:** +- requirements.md (business goals, FRs, constraints, success criteria) +- adrs/*.md (all ADR files with Category field for grouping) + +**Note:** Do not add Non-Functional Requirements (performance, security, scalability, etc.). If quality topics need coverage, describe them as architecture quality goals in narrative form only—never as NFR-XXX-001 style requirements. + +**Placeholders:** +- None (all content directly from MD files) + +### Tab 3: Architecture + +**File:** `tab_architecture_template.html` + +**SCOPE:** +- INCLUDES: C4 diagrams (Context/Container/Component), Deployment, Solution strategy, Quality attributes +- EXCLUDES: ADRs → Requirements, API details → Technical Spec, Code → Guides + +**Content Elements:** +- **C4 Diagrams:** 4 levels in Mermaid syntax (preserved exactly as in architecture.md): + - System Context (C4 Level 1) + - Container Diagram (C4 Level 2) + - Component Diagram (C4 Level 3) + - Deployment Diagram +- **Solution Strategy:** Architecture pattern, API design approach +- **Quality Attributes:** Scalability, Security, Maintainability approaches + +**Data Sources:** +- architecture.md (all content) + +**Placeholders:** +- None (all content directly from architecture.md) + +**EXCLUDES:** +- Tech stack table → moved to Technical Spec tab +- ADRs → moved to Requirements tab + +### Tab 4: Technical Specification + +**File:** `tab_technical_spec_template.html` + +**SCOPE:** +- INCLUDES: Tech stack (detailed table), API endpoints, Authentication, Error codes, ER diagram, Data dictionary, Integrations, Deployment, Testing strategy (Risk-Based) +- EXCLUDES: Requirements → Requirements tab, Architecture diagrams → Architecture tab, How-to guides → Guides tab + +**Content Elements:** +- **Technology Stack:** Detailed table (Category | Technology | Version | Purpose) - includes Frontend, Backend, Database, Infrastructure, DevOps categories +- **API Endpoints:** Table grouped by resource (Endpoint | Method | Description | Request | Response) +- **Authentication:** Auth mechanism description (JWT, OAuth, etc.) +- **Error Codes:** Standard error codes table (Code | Message | Description) +- **Data Model:** ER diagram in Mermaid + Data Dictionary table (Entity | Attributes | Description) +- **Third-Party Integrations:** External services table (Service | Purpose | API Documentation) +- **Deployment Infrastructure:** Infrastructure description (cloud provider, services) +- **Testing Strategy:** Risk-Based Testing approach (2-5 E2E, 3-8 Integration, 5-15 Unit tests per Story, total 10-28 max) + +**Data Sources:** +- technical_specification.md (all content) +- architecture.md (tech stack section - moved here) + +**Placeholders:** +- None (all content directly from MD files) + +### Tab 5: Roadmap + +**File:** `tab_roadmap_template.html` + +**SCOPE:** +- INCLUDES: Kanban board (3 columns), Epic cards, Progress bars (%), Milestones +- EXCLUDES: Individual stories → Linear, Daily tasks → task tracker, Team assignments, Implementation details → Technical Spec + +**Content Elements:** +- **Kanban Board:** 3 columns layout (Todo | In Progress | Done) +- **Epic Cards:** For each Epic from kanban_board.md: + - Epic number + title (h3) + - Description (p) + - Stories count: X/Y completed + - Target date or Completed date + - Status badge (status-todo | status-progress | status-done) + - Progress bar with % width +- **Milestones:** Quarterly milestones list with status indicators + +**Data Sources:** +- kanban_board.md (Epic Story Counters table - Epic number, title, status, story counts, target dates) +- requirements.md (Epic descriptions) +- architecture.md (Epic technical context) + +**Placeholders:** +- None (all content generated from kanban_board.md) + +**Epic Status Mapping:** +- Todo → kanban-todo column, status-todo badge, 0% progress +- In Progress → kanban-progress column, status-progress badge, calculated % progress +- Done → kanban-done column, status-done badge, 100% progress + +### Tab 6: Guides + +**File:** `tab_guides_template.html` + +**SCOPE:** +- INCLUDES: Getting started, How-to guides (task-oriented), Best practices, Troubleshooting, Contributing, External resources +- EXCLUDES: API reference → Technical Spec, Architecture → Architecture tab, Requirements → Requirements tab + +**Content Elements:** +- **Getting Started:** Prerequisites, Installation steps (code blocks), Verification checklist +- **How-To Guides:** Task-oriented guides (How to Add Product, How to Test API, etc.) - steps in ordered lists +- **Best Practices:** Code style, Testing approach, Design patterns +- **Troubleshooting:** Common issues with solutions (h3 per issue + list) +- **Contributing Guidelines:** Fork, branch, test, submit PR workflow +- **External Resources:** Links to framework docs, third-party docs (target="_blank") + +**Data Sources:** +- docs/guides/*.md (all guide files) +- README.md (getting started section) +- technical_specification.md (testing strategy) + +**Placeholders:** +- None (all content directly from guide files) + +## Build Process + +**Script:** `build-presentation.js` (Node.js) + +**Logic:** +1. Read `presentation_template.html` +2. Read all 6 tab files from `tabs/` directory +3. Inject tab content into template (replace `` etc.) +4. Read `styles.css` and inline into ``); + console.log(' ✓ CSS inlined'); +} else { + console.log(' ⚠ styles.css not found'); +} + +// 4. Inline JavaScript +console.log('⚡ Inlining scripts.js...'); +if (fs.existsSync('scripts.js')) { + const js = fs.readFileSync('scripts.js', 'utf-8'); + html = html.replace('', ``); + console.log(' ✓ JS inlined'); +} else { + console.log(' ⚠ scripts.js not found'); +} + +// 5. Write final presentation +const outputPath = path.join('..', 'presentation_final.html'); +console.log(`\n📦 Writing ${outputPath}...`); +fs.writeFileSync(outputPath, html, 'utf-8'); + +// 6. Calculate file size +const stats = fs.statSync(outputPath); +const sizeKB = (stats.size / 1024).toFixed(2); +console.log(` ✓ File size: ${sizeKB} KB`); + +console.log('\n✅ Build complete!'); +console.log(` Open: ${outputPath}`); diff --git a/skills/ln-115-presentation-creator/references/mermaid_guidelines.md b/skills/ln-115-presentation-creator/references/mermaid_guidelines.md new file mode 100644 index 0000000..26cecaf --- /dev/null +++ b/skills/ln-115-presentation-creator/references/mermaid_guidelines.md @@ -0,0 +1,389 @@ +# Mermaid.js Guidelines for x-html-builder + +This guide provides best practices for working with Mermaid.js diagrams in HTML presentations with tab-based navigation. + +## Version and CDN + +**Current Version:** Mermaid v11.12.1 (latest stable as of 2025) + +**Recommended CDN:** +```html + + + + + +``` + +**Why v11?** +- Latest features and bug fixes +- Improved performance +- Better error handling +- `mermaid.init()` deprecated (use `mermaid.run()` instead) + +--- + +## Initialization for Tab-Based Presentations + +**Critical Setting:** `startOnLoad: false` + +**Why?** +- Tabs with `display: none` prevent diagrams from rendering correctly +- Diagrams need manual rendering when tab becomes visible +- Allows precise control over rendering timing + +**Configuration:** +```javascript +mermaid.initialize({ + startOnLoad: false, // Manual control for tab switching + theme: 'default', // or 'dark', 'forest', 'neutral' + securityLevel: 'loose', // For trusted content (allows HTML labels) + logLevel: 1, // 0=none, 1=error, 2=warn, 3=info + flowchart: { + useMaxWidth: true, // Responsive diagrams + htmlLabels: true // Rich text support + } +}); +``` + +--- + +## Rendering Strategies + +### Strategy 1: Render Once Per Tab (Recommended) + +**Best for:** Static content with tab navigation + +```javascript +document.addEventListener('DOMContentLoaded', async function() { + // Initialize Mermaid + mermaid.initialize({ startOnLoad: false }); + + // Render initially active tab + const activeTab = document.querySelector('.tab-content.active'); + if (activeTab && !activeTab.dataset.mermaidRendered) { + await mermaid.run({ + nodes: activeTab.querySelectorAll('.mermaid'), + suppressErrors: true + }); + activeTab.dataset.mermaidRendered = 'true'; // Mark as rendered + } +}); + +async function switchTab(tabName) { + // ... tab switching logic ... + + // Render diagrams only if not already rendered + const activeTab = document.getElementById(`${tabName}-tab`); + if (activeTab && !activeTab.dataset.mermaidRendered) { + await mermaid.run({ + nodes: activeTab.querySelectorAll('.mermaid'), + suppressErrors: true + }); + activeTab.dataset.mermaidRendered = 'true'; + } +} +``` + +**Benefits:** +- ✅ Performance: Each tab rendered only once +- ✅ No duplicate diagrams +- ✅ Minimal re-rendering overhead + +### Strategy 2: Render All on Load + +**Best for:** Small number of tabs (<5), simple diagrams + +```javascript +document.addEventListener('DOMContentLoaded', async function() { + mermaid.initialize({ startOnLoad: false }); + + // Render ALL diagrams at once + await mermaid.run({ + querySelector: '.mermaid', + suppressErrors: true + }); +}); +``` + +**Benefits:** +- ✅ Simple implementation +- ✅ No tab-switch delays +- ❌ Slower initial load for many diagrams + +### Strategy 3: Manual Rendering API + +**Best for:** Dynamic content from API, programmatic diagram generation + +```javascript +const graphDefinition = ` + graph TD + A[Client] --> B[Load Balancer] + B --> C[Server1] + B --> D[Server2] +`; + +const { svg } = await mermaid.render('uniqueId', graphDefinition); +document.getElementById('diagram-container').innerHTML = svg; +``` + +**Benefits:** +- ✅ Full control over rendering +- ✅ Can modify SVG before insertion +- ✅ Works with dynamic content + +--- + +## Common Errors and Solutions + +| Error | Cause | Solution | +|-------|-------|----------| +| **Diagrams not rendering in hidden tabs** | `startOnLoad: true` + `display: none` | Use `startOnLoad: false` + `mermaid.run()` on tab switch | +| **Duplicate diagrams** | Re-rendering already rendered content | Cache rendered tabs with `data-mermaid-rendered` attribute | +| **"mermaid.init is deprecated"** | Using old API | Replace `mermaid.init()` with `mermaid.run()` | +| **SVG sizing issues** | Rendering while element is hidden | Add `setTimeout(... , 50)` before rendering to ensure tab is visible | +| **Parsing errors break page** | Invalid Mermaid syntax | Use `suppressErrors: true` in `mermaid.run()` | +| **Fonts not loaded** | Rendering before fonts ready | Wait for `DOMContentLoaded` + small delay (50-100ms) | +| **Different themes on tabs** | Theme not applied to new renders | Re-initialize theme before rendering: `mermaid.initialize({ theme: 'dark' })` | + +--- + +## Performance Optimization + +### 1. Lazy Rendering +Only render diagrams when tab becomes visible (Strategy 1). + +### 2. Caching +Use `data-mermaid-rendered` attribute to avoid re-rendering: +```javascript +if (!element.dataset.mermaidRendered) { + await mermaid.run({ nodes: [element] }); + element.dataset.mermaidRendered = 'true'; +} +``` + +### 3. Batch Rendering +Render multiple diagrams in one `mermaid.run()` call: +```javascript +// Good: One call for all diagrams in tab +await mermaid.run({ nodes: tab.querySelectorAll('.mermaid') }); + +// Bad: Multiple calls +diagrams.forEach(d => mermaid.run({ nodes: [d] })); +``` + +### 4. Error Suppression (Production) +Prevent parsing errors from breaking the page: +```javascript +await mermaid.run({ suppressErrors: true }); +``` + +### 5. Async/Await +Always use async/await for predictable rendering: +```javascript +async function renderDiagrams() { + await mermaid.run({ ... }); // Wait for completion + console.log('Rendering complete'); +} +``` + +--- + +## Security Levels + +**Choose based on content trust level:** + +### `loose` (Recommended for Documentation) +```javascript +mermaid.initialize({ securityLevel: 'loose' }); +``` +- Allows HTML labels +- Allows some scripts in labels +- **Use for:** Internal docs, trusted content + +### `strict` (User-Generated Content) +```javascript +mermaid.initialize({ securityLevel: 'strict' }); +``` +- Blocks all scripts +- Sanitizes HTML +- **Use for:** User-submitted diagrams, public content + +### `antiscript` (Middle Ground) +```javascript +mermaid.initialize({ securityLevel: 'antiscript' }); +``` +- Removes scripts from output +- Allows safe HTML + +--- + +## Code Examples + +### Complete Tab-Based Implementation + +```javascript +document.addEventListener('DOMContentLoaded', async function() { + // Initialize Mermaid + if (typeof mermaid !== 'undefined') { + mermaid.initialize({ + startOnLoad: false, + theme: 'default', + securityLevel: 'loose', + logLevel: 1, + flowchart: { + useMaxWidth: true, + htmlLabels: true + } + }); + + // Render initially active tab + setTimeout(async () => { + const activeTab = document.querySelector('.tab-content.active'); + if (activeTab && !activeTab.dataset.mermaidRendered) { + try { + await mermaid.run({ + nodes: activeTab.querySelectorAll('.mermaid'), + suppressErrors: true + }); + activeTab.dataset.mermaidRendered = 'true'; + } catch (err) { + console.error('Mermaid rendering error:', err); + } + } + }, 100); + } + + // Tab switching + async function switchTab(tabName) { + // ... tab activation logic ... + + // Render diagrams if not already rendered + if (typeof mermaid !== 'undefined') { + const activeTab = document.getElementById(`${tabName}-tab`); + if (activeTab && !activeTab.dataset.mermaidRendered) { + setTimeout(async () => { + try { + await mermaid.run({ + nodes: activeTab.querySelectorAll('.mermaid'), + suppressErrors: true + }); + activeTab.dataset.mermaidRendered = 'true'; + } catch (err) { + console.error('Mermaid rendering error on tab switch:', err); + } + }, 50); + } + } + } +}); +``` + +### Error Handling with Fallback + +```javascript +async function renderMermaidSafe(element) { + try { + await mermaid.run({ nodes: [element] }); + } catch (err) { + console.error('Mermaid error:', err); + element.innerHTML = ` +
+ ⚠️ Diagram rendering failed. Check syntax. +
+ `; + } +} +``` + +--- + +## Migration Notes: v10 → v11 + +**Breaking Changes:** +- ❌ `mermaid.init()` is deprecated → Use `mermaid.run()` +- ⚠️ Some theme options renamed (check docs) + +**Recommended Changes:** +```javascript +// Old (v10) +mermaid.init(undefined, '.mermaid'); + +// New (v11) +await mermaid.run({ querySelector: '.mermaid' }); +``` + +**CDN Update:** +```html + + + + + +``` + +**Compatibility:** +- ✅ All diagram types (flowchart, sequence, class, ER, etc.) work in v11 +- ✅ Themes are compatible +- ✅ Configuration options mostly unchanged + +--- + +## Troubleshooting Checklist + +When diagrams don't render: + +1. **Check CDN loading:** + ```javascript + console.log(typeof mermaid); // Should be 'object', not 'undefined' + ``` + +2. **Check initialization:** + ```javascript + console.log(mermaid.initialize); // Should be a function + ``` + +3. **Check element visibility:** + ```javascript + const el = document.querySelector('.mermaid'); + console.log(window.getComputedStyle(el).display); // Should NOT be 'none' + ``` + +4. **Check for syntax errors:** + - Open browser console + - Look for Mermaid parsing errors + - Validate syntax at https://mermaid.live + +5. **Check timing:** + - Are you rendering before DOM is ready? + - Is element visible when rendering? + - Try adding `setTimeout(... , 100)` delay + +--- + +## Best Practices Summary + +✅ **DO:** +- Use `startOnLoad: false` for tab-based layouts +- Cache rendered tabs with `data-mermaid-rendered` +- Use async/await for predictable rendering +- Add error handling with `suppressErrors: true` +- Wait for element visibility before rendering +- Use `mermaid.run()` (not deprecated `init()`) + +❌ **DON'T:** +- Use `startOnLoad: true` with hidden tabs +- Re-render already rendered diagrams +- Render while element has `display: none` +- Use `mermaid.init()` (deprecated) +- Ignore parsing errors in production +- Mix rendering strategies + +--- + +**Version:** 1.0.0 +**Last Updated:** 2025-11-06 +**Mermaid Version:** v11.12.1 +**Compatible with:** x-html-builder v2.3.1+ diff --git a/skills/ln-115-presentation-creator/references/presentation_readme_template.md b/skills/ln-115-presentation-creator/references/presentation_readme_template.md new file mode 100644 index 0000000..a2714ea --- /dev/null +++ b/skills/ln-115-presentation-creator/references/presentation_readme_template.md @@ -0,0 +1,146 @@ +# {{PROJECT_NAME}} - Presentation + +> **SCOPE:** Navigation hub for project presentation (HTML presentation access, customization guide, build instructions ONLY). DO NOT add here: Project documentation → docs/project/, Architecture details → docs/project/architecture.md, Technical specs → docs/project/tech_stack.md + +--- + +## Purpose + +This directory contains the interactive HTML presentation for **{{PROJECT_NAME}}**, generated from project documentation (requirements, architecture, technical specifications). + +**Use this when:** +- Presenting project overview to stakeholders +- Onboarding new team members +- Sharing project architecture visually +- Creating project demos + +--- + +## Quick Navigation + +**Main Presentation:** +- [presentation_final.html](presentation_final.html) - Open this in your browser + +**Modular Structure:** +- [assets/presentation_template.html](assets/presentation_template.html) - Base template +- [assets/styles.css](assets/styles.css) - Styling +- [assets/scripts.js](assets/scripts.js) - Tab switching logic +- [assets/tabs/](assets/tabs/) - Individual tab content (tab_overview.html, tab_requirements.html, tab_architecture.html, tab_technical_spec.html, tab_roadmap.html, tab_guides.html) +- [assets/build-presentation.js](assets/build-presentation.js) - Build script + +**⚠️ IMPORTANT: presentation_final.html is a GENERATED file** +- DO NOT edit presentation_final.html directly - changes will be overwritten on next build +- ALL changes must be made in source files (tabs/*.html, styles.css, scripts.js, presentation_template.html) +- Rebuild after source changes: `node docs/presentation/assets/build-presentation.js` + +--- + +## Customization Guide + +### Editing Content + +1. **Edit individual tabs** in `assets/tabs/`: + - `tab_overview.html` - Project overview and key information + - `tab_requirements.html` - Functional requirements and acceptance criteria + - `tab_architecture.html` - System architecture and C4 diagrams + - `tab_technical_spec.html` - Technology stack, API, database (or specialized tabs) + - `tab_roadmap.html` - Project roadmap and milestones + - `tab_guides.html` - Quick guides and best practices + +2. **Update styles** in `assets/css/custom.css`: + - Modify colors, fonts, spacing + - Customize section backgrounds + - Adjust diagram styles + +3. **Modify behavior** in `assets/js/custom.js`: + - Add custom interactions + - Implement navigation helpers + - Integrate analytics + +### Presentation Update Workflow + +**⚠️ CRITICAL RULE: NEVER edit presentation_final.html directly (it's a generated file)** + +Follow this workflow for ALL presentation updates: + +1. **Identify what to change:** + - Content update → Edit `assets/tabs/tab_*.html` (6 files) + - Styling update → Edit `assets/styles.css` + - Behavior update → Edit `assets/scripts.js` + - Layout update → Edit `assets/presentation_template.html` + +2. **Make changes ONLY in source files:** + - Tab content: `assets/tabs/tab_overview.html`, `tab_requirements.html`, `tab_architecture.html`, `tab_technical_spec.html`, `tab_roadmap.html`, `tab_guides.html` + - Styling: `assets/styles.css` + - JavaScript: `assets/scripts.js` + - Template: `assets/presentation_template.html` + +3. **Rebuild presentation:** + ```bash + cd docs/presentation + node assets/build-presentation.js + ``` + +4. **Verify changes:** + - Open `presentation_final.html` in browser + - Check all tabs load correctly + - Verify diagrams render properly + - Test navigation between tabs + +5. **Commit BOTH:** + - Source files (assets/tabs/, assets/*.{css,js,html}) + - Regenerated `presentation_final.html` + +**Why this matters:** presentation_final.html is auto-generated by combining all source files. Direct edits will be lost on next rebuild. + +--- + +## Build Instructions + +**Prerequisites:** +- Project documentation in `docs/project/` (requirements.md, architecture.md, tech_stack.md, etc.) + +**Build Process:** +1. Run skill: `ln-115-presentation-creator` +2. Skill reads documentation from `docs/project/` +3. Generates HTML tabs in `assets/tabs/` +4. Combines tabs into `presentation_final.html` +5. Creates this README for navigation + +**Rebuild Triggers:** +- Updated project documentation +- New architecture diagrams +- Changed requirements or roadmap +- Added new guides + +--- + +## Maintenance + +**Last Updated:** {{LAST_UPDATED}} + +**Update Triggers:** +- Documentation updates in docs/project/ +- New C4 diagrams or Mermaid charts +- Roadmap or milestone changes +- Design system updates + +**Verification:** +- [ ] presentation_final.html opens without errors +- [ ] All tabs load correctly (Overview, Requirements, Architecture, etc.) +- [ ] Mermaid diagrams render properly +- [ ] Navigation between tabs works +- [ ] All links to documentation are valid + +--- + +## Related Documentation + +- [Project Documentation](../project/README.md) - Source for presentation content +- [Architecture Diagrams](../project/architecture.md) - C4 Model diagrams +- [Requirements](../project/requirements.md) - Functional requirements + +--- + +**Template Version:** 1.0.0 +**Last Updated:** {{LAST_UPDATED}} diff --git a/skills/ln-115-presentation-creator/references/presentation_template.html b/skills/ln-115-presentation-creator/references/presentation_template.html new file mode 100644 index 0000000..1a3629e --- /dev/null +++ b/skills/ln-115-presentation-creator/references/presentation_template.html @@ -0,0 +1,66 @@ + + + + + + E-Commerce Platform - Documentation + + + + + + + +
+ +
+

E-Commerce Platform

+

Modern Online Shopping Solution

+
+ + + + + +
+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ + + +
+ + + + diff --git a/skills/ln-115-presentation-creator/references/scripts.js b/skills/ln-115-presentation-creator/references/scripts.js new file mode 100644 index 0000000..99f5442 --- /dev/null +++ b/skills/ln-115-presentation-creator/references/scripts.js @@ -0,0 +1,124 @@ +/** + * Presentation Scripts + * + * Features: + * - Tab switching with state persistence (localStorage) + * - Collapsible sections + * - Mermaid diagram initialization + * - Smooth scrolling + */ + +document.addEventListener('DOMContentLoaded', async function() { + // Initialize Mermaid with manual control for tab switching + if (typeof mermaid !== 'undefined') { + mermaid.initialize({ + startOnLoad: false, // Manual control for better tab switching + theme: 'default', + securityLevel: 'loose', + logLevel: 1, // Only show errors + flowchart: { + useMaxWidth: true, + htmlLabels: true + } + }); + + // Render diagrams in the initially active tab (only once) + setTimeout(async () => { + const activeTab = document.querySelector('.tab-content.active'); + if (activeTab && !activeTab.dataset.mermaidRendered) { + try { + await mermaid.run({ + nodes: activeTab.querySelectorAll('.mermaid'), + suppressErrors: true + }); + activeTab.dataset.mermaidRendered = 'true'; + } catch (err) { + console.error('Mermaid rendering error:', err); + } + } + }, 100); + } + + // Tab Switching + const tabButtons = document.querySelectorAll('.tab-button'); + const tabPanes = document.querySelectorAll('.tab-content'); + + // Load saved tab from localStorage + const savedTab = localStorage.getItem('activeTab') || 'overview'; + switchTab(savedTab); + + tabButtons.forEach(button => { + button.addEventListener('click', function() { + const tabName = this.getAttribute('data-tab'); + switchTab(tabName); + }); + }); + + async function switchTab(tabName) { + // Update buttons + tabButtons.forEach(btn => { + btn.classList.remove('active'); + if (btn.getAttribute('data-tab') === tabName) { + btn.classList.add('active'); + } + }); + + // Update panes + tabPanes.forEach(pane => { + pane.classList.remove('active'); + if (pane.id === `${tabName}-tab`) { + pane.classList.add('active'); + } + }); + + // Save to localStorage + localStorage.setItem('activeTab', tabName); + + // Render Mermaid diagrams in newly activated tab (only once per tab) + if (typeof mermaid !== 'undefined') { + const activeTab = document.getElementById(`${tabName}-tab`); + if (activeTab && !activeTab.dataset.mermaidRendered) { + setTimeout(async () => { + try { + await mermaid.run({ + nodes: activeTab.querySelectorAll('.mermaid'), + suppressErrors: true + }); + activeTab.dataset.mermaidRendered = 'true'; + } catch (err) { + console.error('Mermaid rendering error on tab switch:', err); + } + }, 50); + } + } + + // Scroll to top + window.scrollTo({ top: 0, behavior: 'smooth' }); + } + + // Make switchTab available globally for inline onclick handlers + window.switchTab = switchTab; + + // Search functionality + const searchInput = document.getElementById('search'); + if (searchInput) { + searchInput.addEventListener('input', function() { + const query = this.value.toLowerCase(); + // Basic search implementation - can be enhanced + if (query.length > 2) { + console.log('Searching for:', query); + // TODO: Implement search across all tabs + } + }); + } + + // Collapsible sections (details/summary elements) + document.querySelectorAll('details').forEach(detail => { + detail.addEventListener('toggle', function() { + if (this.open) { + // Scroll into view when expanded + this.scrollIntoView({ behavior: 'smooth', block: 'nearest' }); + } + }); + }); +}); diff --git a/skills/ln-115-presentation-creator/references/styles.css b/skills/ln-115-presentation-creator/references/styles.css new file mode 100644 index 0000000..eb67306 --- /dev/null +++ b/skills/ln-115-presentation-creator/references/styles.css @@ -0,0 +1,778 @@ +/* ==================== CSS Variables ==================== */ +:root { + --primary-color: #2563eb; + --secondary-color: #1e40af; + --success-color: #10b981; + --warning-color: #f59e0b; + --danger-color: #ef4444; + --text-color: #1f2937; + --text-light: #6b7280; + --bg-color: #ffffff; + --bg-light: #f9fafb; + --bg-dark: #f3f4f6; + --border-color: #e5e7eb; + --code-bg: #f3f4f6; + --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1); + --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1); +} + +/* ==================== Global Styles ==================== */ +* { + margin: 0; + padding: 0; + box-sizing: border-box; +} + +body { + font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; + line-height: 1.6; + color: var(--text-color); + background-color: var(--bg-light); +} + +/* ==================== Container ==================== */ +.container { + max-width: 1200px; + margin: 0 auto; + padding: 20px; +} + +/* ==================== Header ==================== */ +.header { + text-align: center; + padding: 40px 20px; + background: linear-gradient(135deg, var(--primary-color), var(--secondary-color)); + color: white; + border-radius: 8px; + margin-bottom: 30px; + box-shadow: var(--shadow-lg); +} + +.header h1 { + font-size: 2.5rem; + margin-bottom: 10px; + text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3); + font-weight: 700; +} + +.subtitle { + font-size: 1.1rem; + opacity: 0.95; + text-shadow: 0 1px 2px rgba(0, 0, 0, 0.2); +} + +/* ==================== Tabs Navigation ==================== */ +.tabs { + display: flex; + gap: 5px; + margin-bottom: 20px; + flex-wrap: wrap; +} + +.tab-button { + flex: 1; + min-width: 120px; + padding: 12px 20px; + background-color: var(--bg-color); + border: 2px solid var(--border-color); + border-radius: 8px 8px 0 0; + cursor: pointer; + font-size: 1rem; + font-weight: 500; + color: var(--text-color); + transition: all 0.3s ease; +} + +.tab-button:hover { + background-color: var(--bg-dark); + border-color: var(--primary-color); +} + +.tab-button.active { + background-color: var(--primary-color); + color: white; + border-color: var(--primary-color); +} + +/* ==================== Tab Content ==================== */ +.content { + background-color: var(--bg-color); + border-radius: 8px; + padding: 40px; + box-shadow: var(--shadow); + min-height: 500px; +} + +.tab-content { + display: none; +} + +.tab-content.active { + display: block; + animation: fadeIn 0.3s ease; +} + +@keyframes fadeIn { + from { opacity: 0; transform: translateY(10px); } + to { opacity: 1; transform: translateY(0); } +} + +/* ==================== Typography ==================== */ +h1 { + font-size: 2rem; + color: var(--primary-color); + margin-bottom: 20px; +} + +h2 { + font-size: 1.75rem; + color: var(--primary-color); + margin-bottom: 20px; + padding-bottom: 10px; + border-bottom: 3px solid var(--primary-color); +} + +h3 { + font-size: 1.5rem; + color: var(--secondary-color); + margin-top: 30px; + margin-bottom: 15px; +} + +h4 { + font-size: 1.2rem; + color: var(--text-color); + margin-top: 20px; + margin-bottom: 10px; +} + +p { + margin-bottom: 15px; + line-height: 1.8; +} + +ul, ol { + margin-left: 30px; + margin-bottom: 15px; +} + +li { + margin-bottom: 8px; +} + +section { + margin-bottom: 40px; +} + +/* ==================== Code Blocks ==================== */ +code { + background-color: var(--code-bg); + padding: 2px 6px; + border-radius: 4px; + font-family: "Monaco", "Courier New", monospace; + font-size: 0.9em; + color: var(--danger-color); +} + +pre { + background-color: var(--code-bg); + padding: 15px; + border-radius: 8px; + overflow-x: auto; + margin-bottom: 20px; + border-left: 4px solid var(--primary-color); +} + +pre code { + background-color: transparent; + padding: 0; + color: var(--text-color); +} + +/* ==================== Tables ==================== */ +table { + width: 100%; + border-collapse: collapse; + margin-bottom: 20px; + box-shadow: var(--shadow); +} + +thead { + background-color: var(--primary-color); + color: white; +} + +th, td { + padding: 12px; + text-align: left; + border-bottom: 1px solid var(--border-color); +} + +tbody tr:hover { + background-color: var(--bg-light); +} + +/* ==================== Cards ==================== */ +.card { + background-color: var(--bg-light); + border-radius: 8px; + padding: 20px; + margin-bottom: 20px; + box-shadow: var(--shadow); + border-left: 4px solid var(--primary-color); +} + +.card h4 { + margin-top: 0; + color: var(--primary-color); +} + +/* ==================== Badges ==================== */ +.badge { + display: inline-block; + padding: 4px 10px; + border-radius: 12px; + font-size: 0.85rem; + font-weight: 600; + margin-right: 5px; +} + +.badge-success { + background-color: var(--success-color); + color: white; +} + +.badge-warning { + background-color: var(--warning-color); + color: white; +} + +.badge-danger { + background-color: var(--danger-color); + color: white; +} + +.badge-primary { + background-color: var(--primary-color); + color: white; +} + +/* ==================== Overview Tab Components ==================== */ +/* Role-based Navigation Cards */ +.role-navigation { + margin: 40px 0; +} + +.role-cards { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 20px; + margin-top: 20px; +} + +.role-card { + padding: 20px; + background-color: var(--bg-color); + border: 2px solid var(--border-color); + border-radius: 8px; + cursor: pointer; + transition: all 0.3s ease; + box-shadow: var(--shadow); +} + +.role-card:hover { + border-color: var(--primary-color); + box-shadow: var(--shadow-lg); + transform: translateY(-2px); +} + +.role-card h3 { + font-size: 1.1rem; + margin-top: 0; + margin-bottom: 10px; + color: var(--text-color); +} + +.role-card p { + font-size: 0.9rem; + color: var(--text-light); + margin: 0; +} + +/* Tech Stack Badges */ +.tech-stack-section { + margin: 40px 0; +} + +.tech-badges { + display: flex; + flex-wrap: wrap; + gap: 12px; + margin-top: 15px; +} + +.tech-badge { + padding: 8px 16px; + background-color: var(--bg-light); + border: 1px solid var(--border-color); + border-radius: 6px; + font-size: 0.9rem; + font-weight: 500; + color: var(--text-color); +} + +/* Quick Stats */ +.quick-stats { + margin: 40px 0; +} + +.stats-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); + gap: 20px; + margin-top: 20px; +} + +.stat-card { + padding: 20px; + background-color: var(--bg-light); + border-radius: 8px; + text-align: center; + box-shadow: var(--shadow); +} + +.stat-card h3 { + font-size: 2rem; + color: var(--primary-color); + margin: 0 0 5px 0; +} + +.stat-card p { + font-size: 0.9rem; + color: var(--text-light); + margin: 0; +} + +/* Quick Links */ +/* ==================== Overview Tab - New Components ==================== */ +/* Stakeholders Section */ +.stakeholders-section { + margin: 40px 0; +} + +.stakeholders-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); + gap: 20px; + margin-top: 20px; +} + +.stakeholder-card { + padding: 20px; + background-color: var(--bg-light); + border-radius: 8px; + text-align: center; + box-shadow: var(--shadow); + border-top: 4px solid var(--primary-color); +} + +.stakeholder-card h3 { + font-size: 1rem; + color: var(--text-color); + margin: 0 0 8px 0; +} + +.stakeholder-card p { + font-size: 0.9rem; + margin: 3px 0; +} + +.stakeholder-card .role { + color: var(--text-light); + font-size: 0.85rem; +} + +/* Navigation Guide */ +.navigation-guide { + margin: 40px 0; +} + +.guide-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: 20px; + margin-top: 20px; +} + +.guide-card { + padding: 20px; + background-color: var(--bg-light); + border: 2px solid var(--border-color); + border-radius: 8px; + transition: all 0.3s ease; +} + +.guide-card:hover { + border-color: var(--primary-color); + box-shadow: var(--shadow-lg); + transform: translateY(-2px); +} + +.guide-card h3 { + font-size: 1.1rem; + color: var(--primary-color); + margin: 0 0 10px 0; +} + +.guide-card p { + font-size: 0.9rem; + color: var(--text-color); + margin: 8px 0; +} + +.guide-card .audience { + font-size: 0.85rem; + color: var(--text-light); + font-style: italic; + margin-top: 12px; +} + +/* ==================== Roadmap Tab Components ==================== */ +/* Roadmap Intro */ +.roadmap-intro { + background-color: var(--bg-light); + padding: 20px; + border-radius: 8px; + border-left: 4px solid var(--primary-color); + margin-bottom: 30px; + font-size: 1rem; + line-height: 1.6; +} + +/* Kanban Board - 5 columns layout */ +/* ==================== Epics List (Roadmap) ==================== */ +.epics-list { + display: flex; + flex-direction: column; + gap: 24px; + margin: 30px 0; +} + +.epic-item { + background-color: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: 8px; + padding: 24px; + box-shadow: var(--shadow); + transition: box-shadow 0.3s ease; +} + +.epic-item:hover { + box-shadow: var(--shadow-lg); +} + +.epic-header { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 12px; +} + +.epic-header h3 { + margin: 0; + font-size: 1.4rem; + color: var(--text-color); +} + +.epic-description { + color: var(--text-light); + margin-bottom: 16px; + font-size: 1rem; +} + +.epic-details { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 20px; + margin-bottom: 16px; + padding: 16px; + background-color: var(--bg-light); + border-radius: 6px; +} + +.epic-scope h4 { + font-size: 0.9rem; + text-transform: uppercase; + color: var(--text-light); + margin-bottom: 8px; + font-weight: 600; +} + +.epic-scope ul { + margin: 0; + padding-left: 20px; +} + +.epic-scope li { + font-size: 0.9rem; + margin-bottom: 4px; +} + +.epic-meta { + border-top: 1px solid var(--border-color); + padding-top: 12px; + margin-top: 12px; +} + +.epic-meta p { + margin: 4px 0; + font-size: 0.9rem; + color: var(--text-light); +} + +/* Epic Status Badges */ +.epic-status { + padding: 6px 12px; + border-radius: 12px; + font-size: 0.85rem; + font-weight: 600; + text-transform: uppercase; +} + +.status-done { + background-color: #d1fae5; + color: #065f46; +} + +.status-progress { + background-color: #dbeafe; + color: #1e40af; +} + +.status-todo { + background-color: #f3f4f6; + color: #4b5563; +} + +.status-backlog { + background-color: #fef3c7; + color: #92400e; +} + +/* Out of Scope Items */ +.out-of-scope-items { + margin: 40px 0; +} + +.out-of-scope-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 20px; + margin-top: 20px; +} + +.out-of-scope-card { + background-color: #fef2f2; + border: 2px solid #fca5a5; + border-radius: 8px; + padding: 16px; +} + +.out-of-scope-card h4 { + color: #dc2626; + margin: 0 0 8px 0; +} + +.scope-reason { + font-size: 0.85rem; + color: var(--text-light); + margin-top: 8px; + font-style: italic; +} + +/* Roadmap Legend */ +.roadmap-legend { + margin-top: 32px; + padding: 16px; + background-color: var(--bg-light); + border-radius: 8px; +} + +.status-badges { + display: flex; + gap: 12px; + flex-wrap: wrap; + align-items: center; + font-size: 0.9rem; + margin-top: 12px; +} + +.progress-fill { + background: linear-gradient(90deg, var(--primary-color), var(--secondary-color)); + height: 100%; + border-radius: 4px; + transition: width 0.5s ease; +} + +/* Roadmap Legend */ +.roadmap-legend { + margin: 40px 0; + background-color: var(--bg-light); + padding: 20px; + border-radius: 8px; + border: 1px solid var(--border-color); +} + +.roadmap-legend h3 { + margin-top: 0; + color: var(--primary-color); +} + +.roadmap-legend ul { + margin-left: 20px; +} + +.roadmap-legend li { + margin-bottom: 10px; +} + +/* ==================== Requirements Tab Components ==================== */ +/* Priority Badges */ +.priority-must { + background-color: #fee2e2; + color: #991b1b; + padding: 4px 8px; + border-radius: 4px; + font-size: 0.75rem; + font-weight: 700; + text-transform: uppercase; +} + +/* ADR Accordion */ +.adr-section { + margin: 40px 0; +} + +.adr-group { + margin: 30px 0; +} + +.adr-group h3 { + margin-top: 40px; + margin-bottom: 20px; +} + +details.adr-item { + margin-bottom: 15px; + padding: 15px; + background-color: var(--bg-light); + border: 1px solid var(--border-color); + border-radius: 8px; +} + +details.adr-item summary { + cursor: pointer; + font-weight: 600; + color: var(--primary-color); + font-size: 1.1rem; +} + +details.adr-item summary:hover { + color: var(--secondary-color); +} + +details.adr-item[open] summary { + margin-bottom: 15px; + padding-bottom: 15px; + border-bottom: 2px solid var(--border-color); +} + +/* Collapsible Sections */ +details { + margin-bottom: 15px; +} + +summary { + cursor: pointer; + font-weight: 600; + padding: 10px; + background-color: var(--bg-light); + border-radius: 4px; +} + +summary:hover { + background-color: var(--bg-dark); +} + +/* ==================== Mermaid Diagrams ==================== */ +.mermaid { + background-color: white; + padding: 20px; + border-radius: 8px; + margin: 20px 0; + text-align: center; + border: 1px solid var(--border-color); +} + +/* ==================== Blockquotes ==================== */ +blockquote { + margin: 20px 0; + padding: 15px 20px; + border-left: 4px solid var(--primary-color); + background-color: var(--bg-light); + font-style: italic; + color: var(--text-light); +} + +/* ==================== Footer ==================== */ +.footer { + text-align: center; + padding: 20px; + margin-top: 40px; + color: var(--text-light); + font-size: 0.9rem; + border-top: 2px solid var(--border-color); +} + +/* ==================== Responsive Design ==================== */ +@media (max-width: 768px) { + .header h1 { + font-size: 1.8rem; + } + + .tabs { + flex-direction: column; + } + + .tab-button { + width: 100%; + } + + .content { + padding: 20px; + } + + .epic-details { + grid-template-columns: 1fr; + } + + .out-of-scope-grid { + grid-template-columns: 1fr; + } + + .role-cards { + grid-template-columns: 1fr; + } + + .stats-grid { + grid-template-columns: 1fr; + } + + table { + font-size: 0.9rem; + } + + th, td { + padding: 8px; + } +} diff --git a/skills/ln-115-presentation-creator/references/tabs/tab_architecture.html b/skills/ln-115-presentation-creator/references/tabs/tab_architecture.html new file mode 100644 index 0000000..cb603da --- /dev/null +++ b/skills/ln-115-presentation-creator/references/tabs/tab_architecture.html @@ -0,0 +1,177 @@ + + + + +

Architecture

+ + + +
+

System Context (C4 Level 1)

+

High-level view of the e-commerce platform and its external dependencies.

+
+graph TD + Customer[Customer] + Admin[Administrator] + PaymentGateway[Payment Gateway
Stripe] + EmailService[Email Service
SendGrid] + + System[E-Commerce Platform] + + Customer -->|Browse products,
Place orders| System + Admin -->|Manage products,
View analytics| System + System -->|Process payments| PaymentGateway + System -->|Send notifications| EmailService +
+ + + + +

Container Diagram (C4 Level 2)

+

Containers within the e-commerce platform showing technologies and communication.

+
+graph TD + Customer[Customer
Web Browser] + Admin[Administrator
Web Browser] + + WebApp[Web Application
React 18 SPA] + API[REST API
Node.js + Express] + Database[(Database
PostgreSQL 15)] + Cache[(Cache
Redis)] + + Customer -->|HTTPS| WebApp + Admin -->|HTTPS| WebApp + WebApp -->|JSON/HTTPS| API + API -->|SQL| Database + API -->|Cache queries| Cache +
+ + + + +

Component Diagram (C4 Level 3) - Optional for Technical Audiences

+

Components within the REST API container showing internal structure.

+
+graph TD + API[REST API Container] + + AuthController[Authentication
Controller] + ProductController[Product Catalog
Controller] + CartController[Shopping Cart
Controller] + OrderController[Order
Controller] + + AuthService[Auth Service] + ProductService[Product Service] + CartService[Cart Service] + OrderService[Order Service] + + ProductRepo[Product
Repository] + UserRepo[User
Repository] + CartRepo[Cart
Repository] + OrderRepo[Order
Repository] + + Database[(PostgreSQL)] + Cache[(Redis)] + + ProductController --> ProductService + CartController --> CartService + OrderController --> OrderService + AuthController --> AuthService + + ProductService --> ProductRepo + CartService --> CartRepo + OrderService --> OrderRepo + AuthService --> UserRepo + + ProductRepo --> Database + UserRepo --> Database + CartRepo --> Cache + OrderRepo --> Database +
+ + + + +

Deployment Diagram

+

Infrastructure and deployment architecture on AWS.

+
+graph TD + subgraph "AWS Cloud" + subgraph "Public Subnet" + ALB[Application Load
Balancer] + CloudFront[CloudFront CDN] + end + + subgraph "Private Subnet" + ECS1[ECS Container 1
Node.js API] + ECS2[ECS Container 2
Node.js API] + + RDS[(RDS PostgreSQL
Primary)] + RDSReplica[(RDS PostgreSQL
Read Replica)] + + ElastiCache[(ElastiCache
Redis)] + end + + subgraph "Storage" + S3[S3 Bucket
Static Assets] + end + end + + CloudFront --> S3 + ALB --> ECS1 + ALB --> ECS2 + ECS1 --> RDS + ECS2 --> RDS + ECS1 --> RDSReplica + ECS2 --> RDSReplica + ECS1 --> ElastiCache + ECS2 --> ElastiCache +
+
+ + + + +
+

Key Architecture Highlights

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AspectApproachRationale
Architecture PatternModular MonolithClear domain boundaries (Auth, Catalog, Cart, Orders) - see ADR-001 in Requirements
API DesignStateless APIEnables horizontal scaling without session affinity
Database StrategyPostgreSQL with read replicasACID transactions + scalability through read replicas
CachingRedisSession/cart data and frequently accessed product catalog
InfrastructureDocker containersCloud-native orchestration with Kubernetes
+ +

For detailed quality attributes (Performance, Security, Scalability, Maintainability), see requirements.md in docs/project/.

+
+ diff --git a/skills/ln-115-presentation-creator/references/tabs/tab_guides.html b/skills/ln-115-presentation-creator/references/tabs/tab_guides.html new file mode 100644 index 0000000..f383f3d --- /dev/null +++ b/skills/ln-115-presentation-creator/references/tabs/tab_guides.html @@ -0,0 +1,198 @@ + + + + +

Guides & Resources

+ + + +
+

Getting Started

+ +

Prerequisites

+
    +
  • Node.js 20.x or higher
    • +
  • PostgreSQL 15.x
    • +
  • Redis 7.x (optional for development)
    • +
  • Docker (optional)
    • +
+ +

Installation

+ 
git clone https://github.com/example/ecommerce-platform.git
+cd ecommerce-platform
+npm install
+cp .env.example .env
+# Edit .env with your database credentials
+npm run db:migrate
+npm run dev
+ +

Verification

+

After starting the server, verify installation:

+
    +
  • ✅ Server running at http://localhost:3000
    • +
  • ✅ API health check: curl http://localhost:3000/api/health
    • +
  • ✅ Database migrations applied: npm run db:status
    • +
+
+ + + + +
+

How-To Guides

+ +
+

How to Add a New Product

+
    +
  1. Login as admin: POST /api/auth/login with admin credentials
    2. +
  2. Get JWT token from response
    3. +
  3. Create product: + 
    curl -X POST http://localhost:3000/api/products \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Product Name",
+    "description": "Product Description",
+    "price": 29.99,
+    "stock_quantity": 100,
+    "category": "Electronics"
+  }'
    +
    4. +
  4. Verify product created: GET /api/products/:id
    5. +
+
+ +
+

How to Test API Endpoints

+
    +
  1. Start development server: npm run dev
    2. +
  2. Run tests: +
      +
    • All tests: npm test
      • +
    • E2E tests only: npm run test:e2e
      • +
    • Integration tests: npm run test:integration
      • +
    • Unit tests: npm run test:unit
      • +
    +
    3. +
  3. View coverage report: npm run test:coverage
    4. +
+
+ +
+

How to Deploy to Production

+
    +
  1. Build Docker image: docker build -t ecommerce-api .
    2. +
  2. Push to registry: docker push ecommerce-api:latest
    3. +
  3. Update ECS task definition with new image
    4. +
  4. Deploy via GitHub Actions (automatic on merge to main)
    5. +
  5. Verify deployment: Check CloudWatch logs for startup
    6. +
+
+
+ + + + +
+

Best Practices

+ +

Code Style

+
    +
  • Follow KISS/YAGNI/DRY principles
    • +
  • Use TypeScript for type safety
    • +
  • Keep functions small and focused (< 30 lines)
    • +
  • Use meaningful variable names (no single letters except loops)
    • +
+ +

Testing Approach

+
    +
  • Follow Risk-Based Testing (Priority ≥ 15 scenarios MUST be tested)
    • +
  • E2E tests (2-5 per Story): Critical user flows
    • +
  • Integration tests (3-8 per Story): API endpoints
    • +
  • Unit tests (5-15 per Story): Business logic only
    • +
  • Test OUR code, not frameworks (Express already tested)
    • +
+ +

Design Patterns

+
    +
  • Layered architecture: Controller → Service → Repository
    • +
  • Dependency Injection for testability
    • +
  • Repository pattern for database access
    • +
  • DTO (Data Transfer Objects) for API requests/responses
    • +
+
+ + + + +
+

Troubleshooting

+ +

Database Connection Errors

+

Problem: "Unable to connect to PostgreSQL"

+

Solution:

+
    +
  • Check PostgreSQL is running: pg_isready
    • +
  • Verify .env credentials match database
    • +
  • Check firewall allows port 5432
    • +
+ +

Port Already in Use

+

Problem: "Port 3000 is already in use"

+

Solution:

+
    +
  • Change PORT in .env to different port (e.g., 3001)
    • +
  • Or kill process using port: lsof -ti:3000 | xargs kill
    • +
+ +

JWT Token Expired

+

Problem: "401 Unauthorized - Token expired"

+

Solution:

+
    +
  • Use refresh token: POST /api/auth/refresh with refresh token
    • +
  • Get new access token from response
    • +
  • Tokens expire after 15 minutes for security
    • +
+ +

Tests Failing Randomly

+

Problem: Tests pass locally but fail in CI

+

Solution:

+
    +
  • Check test isolation (no shared state between tests)
    • +
  • Use transactions in tests (rollback after each test)
    • +
  • Seed database with consistent test data
    • +
+
+ + + + +
+

Contributing Guidelines

+
    +
  1. Fork the repository
    2. +
  2. Create branch: git checkout -b feature/your-feature
    3. +
  3. Write code following style guide
    4. +
  4. Write tests: All new code must have tests (85%+ coverage)
    5. +
  5. Run tests: npm test (all must pass)
    6. +
  6. Commit: git commit -m "Add your feature"
    7. +
  7. Push: git push origin feature/your-feature
    8. +
  8. Submit PR with description of changes
    9. +
+
+ + + + +
+

External Resources

+ +
+ diff --git a/skills/ln-115-presentation-creator/references/tabs/tab_overview.html b/skills/ln-115-presentation-creator/references/tabs/tab_overview.html new file mode 100644 index 0000000..c217813 --- /dev/null +++ b/skills/ln-115-presentation-creator/references/tabs/tab_overview.html @@ -0,0 +1,127 @@ + + + + + + +
+

Project Summary

+ +

The Problem

+

Traditional e-commerce platforms struggle with scalability during peak traffic, complex payment integrations, and fragmented inventory management across multiple channels. Businesses need a unified platform that handles high concurrent loads while maintaining data consistency and security.

+ +

Our Solution

+

An enterprise-grade e-commerce platform built with modern web technologies and modular architecture. The system provides seamless online shopping experiences through stateless API design, robust payment processing with PCI DSS compliance, real-time inventory synchronization, and comprehensive customer analytics.

+ +

Business Value

+
    +
  • Scalability: Support 10,000+ concurrent users with horizontal scaling
    • +
  • Reliability: 99.9% uptime SLA with automated failover
    • +
  • Speed to Market: Modular architecture enables rapid feature delivery
    • +
  • Cost Efficiency: Optimized infrastructure reduces operational costs by 30%
    • +
+
+ + + + +
+

Technology Stack

+
+ React 18 + Node.js + PostgreSQL + Redis + Docker + TypeScript +
+
+ + + + +
+

Key Stakeholders

+
+
+

Project Owner

+

John Smith

+

Business Sponsor

+
+
+

Lead Architect

+

Jane Doe

+

Technical Lead

+
+
+

Development Lead

+

Alex Johnson

+

Engineering Manager

+
+
+

Product Manager

+

Sarah Williams

+

Product Strategy

+
+
+
+ + + + +
+

Project Quick Facts

+
+
+

In Progress

+

Project Status

+
+
+

7

+

Total Epics

+
+
+

Cloud

+

Deployment Model

+
+
+

Web + Mobile

+

Target Platforms

+
+
+
+ + + + +
+

Documentation Guide

+
+
+

📋 Requirements

+

What we're building and why - functional requirements only and architecture decisions (ADRs); Non-Functional Requirements are not produced

+

For: Product Owners, Business Analysts, Architects

+
+
+

🏗️ Architecture

+

How the system is designed - C4 diagrams showing context, containers, components, and deployment infrastructure

+

For: Architects, Technical Leads, DevOps Engineers

+
+
+

⚙️ Technical Spec

+

How to interact with the system - API documentation, data models, schemas, and infrastructure configuration

+

For: Developers, QA Engineers, Integration Teams

+
+
+

🗺️ Roadmap

+

Work order and scope boundaries - Kanban board showing epic progress, dependencies, and what's in/out of scope

+

For: Stakeholders, Project Managers, Executives

+
+
+

📚 Guides

+

How to perform practical tasks - step-by-step guides for installation, development, deployment, and integration

+

For: Developers, DevOps Engineers, New Team Members

+
+
+
+ diff --git a/skills/ln-115-presentation-creator/references/tabs/tab_requirements.html b/skills/ln-115-presentation-creator/references/tabs/tab_requirements.html new file mode 100644 index 0000000..cd44ab2 --- /dev/null +++ b/skills/ln-115-presentation-creator/references/tabs/tab_requirements.html @@ -0,0 +1,210 @@ + + + + +

Requirements

+ + + +
+

Functional Requirements

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDPriorityRequirementAcceptance Criteria
FR-AUTH-001MUSTUser Registration and Login
+ Users must be able to register with email/password and login to access personalized features		 +
    +
  • Email validation (RFC 5322 compliant)
    • +
  • Password strength requirements (min 8 chars, uppercase, lowercase, number)
    • +
  • JWT token-based authentication
    • +
+
FR-CATALOG-001MUSTProduct Catalog Display
+ System must display product catalog with search, filters, and pagination		 +
    +
  • Full-text search across product names and descriptions
    • +
  • Filter by category, price range, availability
    • +
  • Paginate results (20 items per page)
    • +
+
FR-CART-001MUSTShopping Cart Management
+ Users must be able to add/remove products to/from cart		 +
    +
  • Add product with quantity selection
    • +
  • Update quantities in cart
    • +
  • Remove items from cart
    • +
  • Cart persists across sessions (logged-in users)
    • +
+
+
+ + + + +
+

📋 Architecture Decision Records

+ +
+

🎯 Strategic Decisions

+ +
+ ADR-001: Microservices vs Monolith Architecture +

Date: 2025-09-15 | Status: Accepted | Category: Strategic

+ +

Context

+

Need to choose architecture pattern for e-commerce platform considering team size, scaling requirements, and deployment complexity.

+ +

Decision

+

Use modular monolith architecture with clear domain boundaries.

+ +

Rationale

+
    +
  • Small team (5 developers) - microservices overhead too high
    • +
  • Faster time to market with simplified deployment
    • +
  • Clear module boundaries allow future microservices extraction
    • +
+ +

Alternatives Considered

+ + + + + + + + + + + + + + + + + + + + + + + +
AlternativeProsConsRejection Reason
MicroservicesIndependent scaling, technology diversityOperational complexity, team overheadTeam too small, premature optimization
Traditional monolithSimplest to buildDifficult to scale, tight couplingNo clear boundaries for future evolution
+ +

Consequences

+

Positive:

+
    +
  • Faster development and deployment
    • +
  • Easier testing and debugging
    • +
  • Lower infrastructure costs
    • +
+

Negative:

+
    +
  • Cannot scale individual modules independently
    • +
  • Requires discipline to maintain module boundaries
    • +
+
+
+ + + + +
+

🔧 Technical Decisions

+ +
+ ADR-002: Database Choice - PostgreSQL vs MongoDB +

Date: 2025-09-18 | Status: Accepted | Category: Technical

+ +

Context

+

Need to select database for e-commerce transactional data considering ACID requirements, scalability, and query complexity.

+ +

Decision

+

Use PostgreSQL 15.x as primary database.

+ +

Rationale

+
    +
  • Strong ACID guarantees for transactions (orders, payments)
    • +
  • JSON support for flexible product attributes
    • +
  • Excellent performance for complex queries
    • +
+ +

Alternatives Considered

+ + + + + + + + + + + + + + + + + + + + + + + +
AlternativeProsConsRejection Reason
MongoDBSchema flexibility, horizontal scalingWeak transaction support, complex queries difficultE-commerce requires strong ACID for financial data
MySQLWidely adopted, good performanceLimited JSON support, fewer featuresPostgreSQL offers better feature set
+ +

Consequences

+

Positive:

+
    +
  • Data integrity guaranteed for financial transactions
    • +
  • Rich ecosystem and tooling
    • +
+

Negative:

+
    +
  • Vertical scaling limitations (mitigated by read replicas)
    • +
  • Schema migrations require careful planning
    • +
+
+
+
+ + + + +
+

Success Criteria

+
    +
  • ✅ MVP handles 1,000+ daily active users
    • +
  • ✅ 99.5% uptime in first 3 months
    • +
  • ✅ Average checkout time < 3 minutes
    • +
  • ✅ 85%+ test coverage (E2E + Integration + Unit)
    • +
  • ✅ Zero critical security vulnerabilities
    • +
+
+ diff --git a/skills/ln-115-presentation-creator/references/tabs/tab_roadmap.html b/skills/ln-115-presentation-creator/references/tabs/tab_roadmap.html new file mode 100644 index 0000000..51a49bc --- /dev/null +++ b/skills/ln-115-presentation-creator/references/tabs/tab_roadmap.html @@ -0,0 +1,315 @@ + + + + +

Roadmap

+ +

This roadmap shows the work order and scope boundaries for our project. Epics are organized by dependencies, with clear scope definition for each.

+ + + +
+ +
+
+

Epic 1: User Management

+ Done +
+

User registration, authentication, profile management, and session handling

+ +
+
+

In Scope

+
    +
  • JWT authentication
    • +
  • Email/password registration
    • +
  • Password reset flow
    • +
  • User profile CRUD operations
    • +
  • Session management
    • +
+
+
+

Out of Scope

+
    +
  • Social login (OAuth)
    • +
  • Multi-factor authentication
    • +
  • Single sign-on (SSO)
    • +
+
+
+ +
+

Dependencies: None (Foundation epic)

+

Success Criteria: JWT authentication, < 2s login time, Password reset flow

+

Progress: 6/6 stories completed (100%)

+
+
+ + +
+
+

Epic 2: Product Catalog

+ Done +
+

Product listing, search, filters, and pagination

+ +
+
+

In Scope

+
    +
  • Full-text search across product names and descriptions
    • +
  • Category filters
    • +
  • Price range filters
    • +
  • Pagination (20 items/page)
    • +
  • Product detail pages
    • +
  • 1000+ SKUs support
    • +
+
+
+

Out of Scope

+
    +
  • AI-powered recommendations
    • +
  • Visual search
    • +
  • Product reviews
    • +
+
+
+ +
+

Dependencies: Epic 1 (User Management for admin features)

+

Success Criteria: Full-text search, 1000+ SKUs, < 1s search response

+

Progress: 8/8 stories completed (100%)

+
+
+ + +
+
+

Epic 3: Shopping Cart

+ In Progress +
+

Cart management with session persistence and inventory validation

+ +
+
+

In Scope

+
    +
  • Add/remove items from cart
    • +
  • Update quantities
    • +
  • Cart persistence across sessions
    • +
  • Real-time inventory validation
    • +
  • Cart subtotal calculation
    • +
+
+
+

Out of Scope

+
    +
  • Wishlist functionality
    • +
  • Share cart
    • +
  • Save for later
    • +
+
+
+ +
+

Dependencies: Epic 2 (Product Catalog)

+

Success Criteria: Cart persists across sessions, real-time inventory sync, < 500ms cart operations

+

Progress: 3/8 stories completed (37%)

+
+
+ + +
+
+

Epic 4: Admin Dashboard

+ In Progress +
+

Product management, inventory control, and analytics dashboard

+ +
+
+

In Scope

+
    +
  • Product CRUD operations
    • +
  • Bulk product import (CSV)
    • +
  • Inventory management
    • +
  • Role-based access control
    • +
  • Real-time analytics dashboard
    • +
  • Sales reports
    • +
+
+
+

Out of Scope

+
    +
  • Customer support tickets
    • +
  • Email campaigns
    • +
  • Advanced BI reports
    • +
+
+
+ +
+

Dependencies: Epic 1 (User Management), Epic 2 (Product Catalog)

+

Success Criteria: Role-based access control, bulk product import, real-time analytics

+

Progress: 2/7 stories completed (28%)

+
+
+ + +
+
+

Epic 5: Payment Gateway

+ Todo +
+

Integrate Stripe for secure payment processing with PCI DSS compliance

+ +
+
+

In Scope

+
    +
  • Stripe payment integration
    • +
  • Credit/debit card payments
    • +
  • Digital wallets (Apple Pay, Google Pay)
    • +
  • PCI DSS compliance
    • +
  • Payment error handling
    • +
  • Refund processing
    • +
+
+
+

Out of Scope

+
    +
  • Cryptocurrency payments
    • +
  • Buy now, pay later (BNPL)
    • +
  • Invoice payments
    • +
+
+
+ +
+

Dependencies: Epic 3 (Shopping Cart)

+

Success Criteria: PCI DSS compliant, < 3s checkout time, support 5+ payment methods

+

Progress: 0/5 stories planned

+
+
+ + +
+
+

Epic 6: Order Management

+ Todo +
+

Order processing, tracking, and fulfillment workflows

+ +
+
+

In Scope

+
    +
  • Order creation and confirmation
    • +
  • Real-time order tracking
    • +
  • Email notifications
    • +
  • Order history
    • +
  • Automated fulfillment workflows
    • +
  • Cancellation and refund flows
    • +
+
+
+

Out of Scope

+
    +
  • Advanced shipping integrations
    • +
  • Returns management portal
    • +
  • International shipping
    • +
+
+
+ +
+

Dependencies: Epic 5 (Payment Gateway)

+

Success Criteria: Real-time order tracking, automated fulfillment notifications, < 1min order confirmation

+

Progress: 0/6 stories planned

+
+
+ + +
+
+

Epic 7: Advanced Analytics

+ Backlog +
+

Customer behavior analytics and recommendations engine

+ +
+
+

In Scope

+
    +
  • Customer behavior tracking
    • +
  • Product recommendations engine
    • +
  • Conversion funnel analytics
    • +
  • A/B testing framework
    • +
  • Personalized user experience
    • +
+
+
+

Out of Scope

+
    +
  • Machine learning models
    • +
  • Predictive analytics
    • +
  • Customer data platform (CDP)
    • +
+
+
+ +
+

Dependencies: Epic 2 (Product Catalog), Epic 6 (Order Management)

+

Success Criteria: 15% increase in conversion rate, personalized recommendations for 80%+ users

+

Progress: 0/9 stories planned

+
+
+
+ + + + +
+

Out of Project Scope

+

The following items are explicitly NOT included in the current project phase:

+ +
+
+

Mobile Native Apps

+

iOS and Android native applications

+

Reason: Focus on responsive web first, native apps planned for Phase 2

+
+ +
+

Multi-Currency Support

+

International payments and currency conversion

+

Reason: Current scope limited to USD, internationalization in future release

+
+ +
+

Social Commerce Integration

+

Social media selling and live shopping features

+

Reason: Not in MVP scope, evaluate after core features stable

+
+ +
+

B2B Wholesale Portal

+

Bulk ordering and wholesale pricing for business customers

+

Reason: B2C focus first, B2B features separate project phase

+
+
+
+ + + + +
+

Status Legend

+
+ Done Completed and deployed + In Progress Currently being developed + Todo Approved and ready to start + Backlog Under evaluation +
+
+ diff --git a/skills/ln-115-presentation-creator/references/tabs/tab_technical_spec.html b/skills/ln-115-presentation-creator/references/tabs/tab_technical_spec.html new file mode 100644 index 0000000..dcaf623 --- /dev/null +++ b/skills/ln-115-presentation-creator/references/tabs/tab_technical_spec.html @@ -0,0 +1,364 @@ + + + + +

Technical Specification

+ + + +
+

Technology Stack

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryTechnologyVersionPurpose
FrontendReact18.2UI framework for SPA
FrontendTypeScript5.2Type-safe JavaScript
BackendNode.js20.xRuntime environment
BackendExpress4.18REST API framework
DatabasePostgreSQL15.xPrimary transactional database
CacheRedis7.xSession & cart caching
InfrastructureDocker24.xContainerization
InfrastructureAWS ECS-Container orchestration
DevOpsGitHub Actions-CI/CD pipeline
+
+ + + + +
+

API Endpoints

+ +

Authentication

+ + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodDescription
/api/auth/registerPOSTRegister new user
/api/auth/loginPOSTLogin and get JWT token
/api/auth/refreshPOSTRefresh JWT token
+ +

Products

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodDescription
/api/productsGETList all products (paginated)
/api/products/:idGETGet product details
/api/productsPOSTCreate new product (admin only)
/api/products/:idPUTUpdate product (admin only)
+ +

Shopping Cart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodDescription
/api/cartGETGet current user's cart
/api/cart/itemsPOSTAdd item to cart
/api/cart/items/:idPUTUpdate item quantity
/api/cart/items/:idDELETERemove item from cart
+ +

Authentication

+

Method: JWT Bearer Token

+ 
Authorization: Bearer <token>
+

Token expires in 15 minutes. Use /api/auth/refresh with refresh token to get new access token.

+ +

Error Codes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeMessageDescription
400Bad RequestInvalid request payload
401UnauthorizedMissing or invalid JWT token
403ForbiddenInsufficient permissions
404Not FoundResource not found
500Internal Server ErrorUnexpected server error
+
+ + + + +
+

Data Models

+ +

Entity Relationship Diagram

+
+erDiagram + USER ||--o{ ORDER : places + USER ||--o{ CART : has + CART ||--|{ CART_ITEM : contains + PRODUCT ||--o{ CART_ITEM : "in" + PRODUCT ||--o{ ORDER_ITEM : "in" + ORDER ||--|{ ORDER_ITEM : contains + ORDER ||--|| PAYMENT : has + + USER { + uuid id PK + string email + string password_hash + string first_name + string last_name + timestamp created_at + } + + PRODUCT { + uuid id PK + string name + text description + decimal price + int stock_quantity + string category + timestamp created_at + } + + CART { + uuid id PK + uuid user_id FK + timestamp updated_at + } + + CART_ITEM { + uuid id PK + uuid cart_id FK + uuid product_id FK + int quantity + } + + ORDER { + uuid id PK + uuid user_id FK + decimal total_amount + string status + timestamp created_at + } + + ORDER_ITEM { + uuid id PK + uuid order_id FK + uuid product_id FK + int quantity + decimal price_at_purchase + } + + PAYMENT { + uuid id PK + uuid order_id FK + string payment_method + string status + string transaction_id + timestamp created_at + } +
+ +

Data Dictionary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EntityKey AttributesDescription
USERemail (unique), password_hashCustomer accounts
PRODUCTname, price, stock_quantityProduct catalog items
CARTuser_idShopping cart (1 per user)
ORDERuser_id, status, total_amountCustomer orders
PAYMENTorder_id, transaction_id, statusPayment transactions
+
+ + + + +
+

Testing Strategy

+

Risk-Based Testing approach - prioritize tests by business impact:

+ +

Test Pyramid

+
    +
  • E2E Tests (2-5 per Story): Critical user flows (checkout, payment, registration)
    • +
  • Integration Tests (3-8 per Story): API endpoints, database interactions
    • +
  • Unit Tests (5-15 per Story): Business logic, validators, utilities
    • +
+ +

Total: 10-28 tests per Story (max)

+ +

Priority Matrix

+

Test scenarios with Priority ≥ 15 MUST be tested:

+ 
Priority = Business Impact (1-5) × Probability (1-5)
+ +

Test Focus

+
    +
  • ✅ Test OUR code (business logic, API endpoints)
    • +
  • ❌ Skip framework code (Express middleware already tested)
    • +
  • ❌ Skip trivial getters/setters (no business logic)
    • +
+
+ diff --git a/skills/ln-116-test-docs-creator/SKILL.md b/skills/ln-116-test-docs-creator/SKILL.md new file mode 100644 index 0000000..6ae23b0 --- /dev/null +++ b/skills/ln-116-test-docs-creator/SKILL.md @@ -0,0 +1,440 @@ +--- +name: ln-116-test-docs-creator +description: Creates test documentation (testing-strategy.md + tests/README.md). Establishes testing philosophy and Story-Level Test Task Pattern. Part of ln-110-documents-pipeline workflow. +--- + +# Test Documentation Creator + +This skill creates and validates test documentation: testing-strategy.md (universal testing philosophy) + tests/README.md (test organization structure and Story-Level Test Task Pattern). + +## When to Use This Skill + +**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator. + +This skill should be used directly when: +- Creating only test documentation (testing-strategy.md + tests/README.md) +- Validating existing test documentation structure and content +- Setting up test philosophy and structure documentation for existing project +- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup) + +## How It Works + +The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation. + +--- + +### Phase 1: Create Test Documentation + +**Objective**: Establish test philosophy and documentation structure. + +**Process**: + +**1.1 Check & create directories**: +- Check if `docs/reference/guides/` exists → create if missing +- Check if `tests/` exists → create if missing +- Log for each: "✓ Created [directory]/" or "✓ [directory]/ already exists" + +**1.2 Check & create documentation files**: +- Check if `docs/reference/guides/testing-strategy.md` exists +- If exists: + - Skip creation + - Log: "✓ testing-strategy.md already exists, proceeding to validation" +- If NOT exists: + - Copy template: `ln-116-test-docs-creator/references/testing_strategy_template.md` → `docs/reference/guides/testing-strategy.md` + - Replace placeholders: + - `[CURRENT_DATE]` — current date (YYYY-MM-DD) + - Log: "✓ Created testing-strategy.md from template" + +- Check if `tests/README.md` exists +- If exists: + - Skip creation + - Log: "✓ tests/README.md already exists, proceeding to validation" +- If NOT exists: + - Copy template: `ln-116-test-docs-creator/references/tests_readme_template.md` → `tests/README.md` + - Replace placeholders: + - `{{DATE}}` — current date (YYYY-MM-DD) + - Log: "✓ Created tests/README.md from template" + +**1.3 Output**: +``` +docs/reference/guides/ +└── testing-strategy.md # Created or existing + +tests/ +└── README.md # Created or existing +``` + +--- + +### Phase 2: Validate Structure + +**Objective**: Ensure test documentation files comply with structural requirements and auto-fix violations. + +**Process**: + +**2.1 Check SCOPE tags**: +- Read both files (testing-strategy.md, tests/README.md) - first 5 lines only +- Check for `` tag in each +- Expected SCOPE tags: + - testing-strategy.md: `` + - tests/README.md: `` +- If missing in either file: + - Use Edit tool to add SCOPE tag at line 1 (before first heading) + - Track violation: `scope_tags_added += 1` + +**2.2 Check required sections**: +- Load expected sections from `references/questions.md` +- For **testing-strategy.md**, required sections: + - "Testing Philosophy" + - "Test Levels" +- For **tests/README.md**, required sections: + - "Test Organization" + - "Running Tests" +- For each file: + - Read file content + - Check if `## [Section Name]` header exists + - If missing: + - Use Edit tool to add section with placeholder content from template + - Track violation: `missing_sections += 1` + +**2.3 Check Maintenance section**: +- For each file (testing-strategy.md, tests/README.md): + - Search for `## Maintenance` header + - If missing: + - Use Edit tool to add at end of file: + ```markdown + ## Maintenance + + **Last Updated:** [current date] + + **Update Triggers:** + - Test framework changes + - Test organization changes + - New test patterns introduced + + **Verification:** + - [ ] All test examples follow current framework syntax + - [ ] Directory structure matches actual tests/ + - [ ] Test runner commands are current + ``` + - Track violation: `maintenance_added += 1` + +**2.4 Check POSIX file endings**: +- For each file: + - Check if file ends with single blank line (LF) + - If missing: + - Use Edit tool to add final newline + - Track fix: `posix_fixed += 1` + +**2.5 Report validation**: +- Log summary: + ``` + ✅ Structure validation complete: + - SCOPE tags: [added N / already present] + - Missing sections: [added N sections] + - Maintenance sections: [added N / already present] + - POSIX endings: [fixed N / compliant] + ``` +- If violations found: "⚠️ Auto-fixed [total] structural violations" + +--- + +### Phase 3: Validate Content + +**Objective**: Ensure each section answers its questions with meaningful content and populate test-specific sections from auto-discovery. + +**Process**: + +**3.1 Load validation spec**: +- Read `references/questions.md` +- Parse questions and validation heuristics for 4 sections (2 per file) + +**3.2 Validate testing-strategy.md sections**: + +For this file, use **standard template content** (no auto-discovery needed): + +1. **Testing Philosophy section**: + - Read section content + - Check validation heuristics from questions.md: + - ✅ Mentions "Risk-Based Testing" + - ✅ Has test pyramid description + - ✅ Mentions priority threshold (≥15) + - ✅ References Story-Level Test Task Pattern + - ✅ Length > 100 words + - If ANY heuristic passes → content valid + - If ALL fail → log warning: "⚠️ testing-strategy.md → Testing Philosophy section may need review" + +2. **Test Levels section**: + - Read section content + - Check validation heuristics from questions.md: + - ✅ Lists 3 levels (E2E, Integration, Unit) + - ✅ Has numeric ranges (2-5, 3-8, 5-15) + - ✅ Explains rationale + - ✅ Length > 150 words + - If ANY heuristic passes → content valid + - If ALL fail → log warning: "⚠️ testing-strategy.md → Test Levels section may need review" + +**Note**: testing-strategy.md is **universal philosophy** - no project-specific auto-discovery needed. + +**3.3 Validate tests/README.md sections with auto-discovery**: + +**Section: Test Organization** + +1. **Auto-discover test framework**: + - Check `package.json` → "devDependencies" and "dependencies": + - Node.js frameworks: jest, vitest, mocha, ava, tap, jasmine + - If found: Extract name and version + - Check `requirements.txt` (if Python project): + - Python frameworks: pytest, nose2, unittest2 + - If found: Extract name and version + - Check `go.mod` (if Go project): + - Go uses built-in testing package + - If framework detected: + - Log: "✓ Test framework detected: [framework]@[version]" + - Track: `framework_detected = "[framework]"` + - If NOT detected: + - Log: "⚠️ No test framework detected. Will use generic test organization." + - Track: `framework_detected = None` + +2. **Auto-discover test directory structure**: + - Use Glob tool to scan tests/ directory: + - Pattern: `"tests/e2e/**/*.{js,ts,py,go}"` + - Pattern: `"tests/integration/**/*.{js,ts,py,go}"` + - Pattern: `"tests/unit/**/*.{js,ts,py,go}"` + - Count files in each directory: + - `e2e_count = len(e2e_files)` + - `integration_count = len(integration_files)` + - `unit_count = len(unit_files)` + - If directories exist: + - Log: "✓ Test structure: [e2e_count] E2E, [integration_count] Integration, [unit_count] Unit tests" + - If directories DON'T exist: + - Create placeholder structure: + ``` + tests/ + e2e/ (empty, ready for E2E tests) + integration/ (empty, ready for Integration tests) + unit/ (empty, ready for Unit tests) + ``` + - Log: "✓ Created test directory structure (will be populated during Story test task execution)" + +3. **Auto-discover naming conventions**: + - For each test file found (from step 2): + - Extract filename pattern: + - `*.test.js` → "*.test.js" convention + - `*.spec.ts` → "*.spec.ts" convention + - `test_*.py` → "test_*.py" convention + - `*_test.go` → "*_test.go" convention + - Count occurrences of each pattern + - Use most common pattern (majority rule) + - If pattern detected: + - Log: "✓ Naming convention: [pattern] (detected from [count] files)" + - If NO files exist: + - Use framework default: + - Jest/Vitest → *.test.js + - Mocha → *.spec.js + - Pytest → test_*.py + - Go → *_test.go + - Log: "✓ Naming convention: [default_pattern] (framework default)" + +4. **Check Test Organization section content**: + - Read section from tests/README.md + - Check validation heuristics: + - ✅ Describes directory structure (e2e/integration/unit) + - ✅ Mentions naming conventions + - ✅ References Story-Level Test Task Pattern + - ✅ Has framework mention + - If ANY heuristic passes → content valid + - If ALL fail → log warning: "⚠️ tests/README.md → Test Organization section needs update" + +**Section: Running Tests** + +1. **Auto-discover test runner command**: + - Read `package.json` → "scripts" → "test" + - If found: + - Extract command value + - Examples: + - `"jest"` → Test runner: "npm test" (runs jest) + - `"vitest"` → Test runner: "npm test" (runs vitest) + - `"mocha"` → Test runner: "npm test" (runs mocha) + - Custom script → Test runner: "npm test" (runs [custom]) + - Log: "✓ Test runner: npm test (runs [command])" + - If NOT found (no package.json or no test script): + - Use default based on detected framework (from step 3.3.1): + - Jest → "npm test" + - Vitest → "npm test" + - Pytest → "pytest" + - Go → "go test ./..." + - Log: "⚠️ No test script found in package.json. Using default '[command]'." + +2. **Auto-discover coverage command** (optional): + - Check `package.json` → "scripts" for: + - "test:coverage" + - "coverage" + - "test:cov" + - If found: + - Extract command + - Log: "✓ Coverage command: npm run [script_name]" + - If NOT found: + - Use framework default: + - Jest → "npm test -- --coverage" + - Vitest → "npm test -- --coverage" + - Pytest → "pytest --cov=src" + - Go → "go test -cover ./..." + - Log: "✓ Coverage command: [default] (framework default)" + +3. **Check Running Tests section content**: + - Read section from tests/README.md + - Check validation heuristics: + - ✅ Has test runner command + - ✅ Mentions coverage + - ✅ Shows how to run specific tests + - ✅ Has command examples + - If ANY heuristic passes → content valid + - If ALL fail → log warning: "⚠️ tests/README.md → Running Tests section needs update" + +**3.4 Report content validation**: +- Log summary: + ``` + ✅ Content validation complete: + - testing-strategy.md: [2 sections checked] + - tests/README.md: [2 sections checked] + - Test framework: [detected framework or "Not detected"] + - Test structure: [e2e/integration/unit counts or "Created placeholder"] + - Naming convention: [pattern or "Framework default"] + - Test runner: [command] + - Coverage command: [command] + ``` + +--- + +## Complete Output Structure + +``` +docs/reference/guides/ +└── testing-strategy.md # Universal testing philosophy (465 lines) + +tests/ +└── README.md # Test organization + Story-Level Pattern (112 lines) +``` + +**Note**: Actual test directories (e2e/, integration/, unit/) created during Story test task execution or Phase 3 if missing. + +--- + +## Reference Files Used + +### Templates + +**Testing Strategy Template**: +- `references/testing_strategy_template.md` - Universal testing philosophy with: + - SCOPE tags (testing philosophy, NOT framework-specific) + - Core Philosophy ("Test YOUR code, not frameworks") + - Risk-Based Testing Strategy (Priority Matrix, test caps) + - Story-Level Testing Pattern + - Test Organization (E2E/Integration/Unit definitions) + - Isolation Patterns (Data Deletion/Transaction Rollback/DB Recreation) + - What To Test vs NOT Test (universal examples) + - Testing Patterns (Arrange-Act-Assert, Mock at the Seam, Test Data Builders) + - Common Issues (Flaky Tests, Slow Tests, Test Coupling) + - Coverage Guidelines + - Verification Checklist + +**Tests README Template**: +- `references/tests_readme_template.md` - Test organization with: + - SCOPE tags (test documentation ONLY) + - Overview (E2E/Integration/Unit test organization) + - Testing Philosophy (brief, link to testing-strategy.md) + - Test Structure (directory tree) + - Story-Level Test Task Pattern (tests in final Story task, NOT scattered) + - Test Execution (project-specific commands) + - Quick Navigation (links to testing-strategy.md, kanban_board, guidelines) + - Maintenance section (Update Triggers, Verification, Last Updated) + +**Validation Specification**: +- `references/questions.md` (v1.0.0) - Question-driven validation: + - Questions each section must answer (4 sections total) + - Validation heuristics (ANY passes → valid) + - Auto-discovery hints (test frameworks, directory structure, naming conventions) + - MCP Ref hints (external research if needed) + +--- + +## Best Practices + +- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks) +- **Parametric validation**: Phase 3 validates 4 sections across 2 files (no code duplication) +- **Auto-discovery first**: Scan test frameworks and directory structure before using defaults +- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation, re-validates on each run) +- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT +- **Story-Level Test Task Pattern**: Tests consolidated in final Story task (ln-350-story-test-planner creates task, ln-334-test-executor implements) +- **Value-Based Testing**: 2-5 E2E, 3-8 Integration, 5-15 Unit per Story (10-28 total max), Priority ≥15 MUST be tested +- **No test code**: This skill creates DOCUMENTATION only, NOT actual tests + +--- + +## Prerequisites + +**Invoked by**: ln-110-documents-pipeline orchestrator + +**Requires**: +- `docs/reference/guides/` directory (created by ln-112-reference-docs-creator or Phase 1 if missing) + +**Creates**: +- `docs/reference/guides/testing-strategy.md` (universal testing philosophy) +- `tests/README.md` (test organization structure) +- Validated structure and content (auto-discovery of test frameworks and directory structure) + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +**✅ Structure Created (Phase 1):** +- [ ] `docs/reference/guides/` directory exists +- [ ] `tests/` directory exists +- [ ] `testing-strategy.md` exists (created or existing) +- [ ] `tests/README.md` exists (created or existing) + +**✅ Structure Validated (Phase 2):** +- [ ] SCOPE tags present in both files (first 5 lines) +- [ ] testing-strategy.md has "Testing Philosophy" and "Test Levels" sections +- [ ] tests/README.md has "Test Organization" and "Running Tests" sections +- [ ] Maintenance sections present in both files at end +- [ ] POSIX file endings compliant (LF, single blank line at EOF) + +**✅ Content Validated (Phase 3):** +- [ ] testing-strategy.md → Testing Philosophy section checked (Risk-Based Testing mentioned) +- [ ] testing-strategy.md → Test Levels section checked (2-5 E2E, 3-8 Integration, 5-15 Unit) +- [ ] tests/README.md → Test Organization section checked or auto-discovered +- [ ] tests/README.md → Running Tests section checked or auto-discovered +- [ ] Test framework detected (if applicable) and logged +- [ ] Test directory structure scanned or created +- [ ] Naming conventions detected or defaults used +- [ ] Test runner command identified or defaults used + +**✅ Reporting:** +- [ ] Phase 1 logged: creation summary +- [ ] Phase 2 logged: structural fixes (if any) +- [ ] Phase 3 logged: content validation summary with auto-discovery results + +--- + +## Technical Details + +**Standards**: +- Story-Level Test Task Pattern +- Value-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total max per Story) +- Risk-Based Testing (Priority ≥15) + +**Language**: English only + +**Auto-Discovery Support**: +- Node.js: jest, vitest, mocha, ava, tap, jasmine +- Python: pytest, nose2, unittest2 +- Go: built-in testing package + +--- + +**Version:** 7.0.0 (MAJOR: Merged validation into worker. Added Phase 2 structure validation + Phase 3 semantic content validation with test framework auto-discovery. Idempotent - can be invoked multiple times.) +**Last Updated:** 2025-11-18 diff --git a/skills/ln-116-test-docs-creator/diagram.html b/skills/ln-116-test-docs-creator/diagram.html new file mode 100644 index 0000000..6518226 --- /dev/null +++ b/skills/ln-116-test-docs-creator/diagram.html @@ -0,0 +1,126 @@ + + + + + + ln-116-test-docs-creator - State Diagram + + + + +
+
+

🧪 ln-116-test-docs-creator

+

Test Documentation Creator - State Diagram

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Create and validate test documentation (testing-strategy.md + tests/README.md)
    • +
  • Worker for: ln-110-documents-pipeline orchestrator
    • +
  • Phases: 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Content Validation)
    • +
  • Auto-Discovery: Test framework detection, directory structure scanning, naming convention detection
    • +
  • Risk-Based Testing: Priority ≥15 scenarios, test caps (2-5 E2E, 3-8 Integration, 5-15 Unit)
    • +
+
+ +
+
+
+ Creation Action +
+
+
+ Validation +
+
+
+ Decision Point +
+
+ +
+
+graph TD + Start([Start: Test Docs Creation]) --> Phase1[Phase 1: CREATE
Check & create test documentation] + + Phase1 --> CheckDirs[Check directories:
docs/reference/guides/, tests/] + CheckDirs --> CreateDirs{Directories
exist?} + CreateDirs -->|No| MakeDirs[Create missing directories] + CreateDirs -->|Yes| CheckFiles + MakeDirs --> CheckFiles + + CheckFiles[Check files:
testing-strategy.md, tests/README.md] + CheckFiles --> FilesExist{Files
exist?} + FilesExist -->|Yes| Preserved[Preserve existing files
Skip creation] + FilesExist -->|No| CreateFiles[Create from templates
Replace DATE placeholders] + + Preserved --> Phase2 + CreateFiles --> Phase2 + + Phase2[Phase 2: Validate Structure
Auto-fix violations] + + Phase2 --> AutoFix[Auto-fix:
SCOPE tags, required sections,
Maintenance sections, POSIX endings] + + AutoFix --> Phase3[Phase 3: Validate Content
Semantic validation + auto-discovery] + + Phase3 --> ValidateStrategy[Validate testing-strategy.md:
Testing Philosophy, Test Levels] + + Phase3 --> AutoDiscovery[Auto-discovery for tests/README.md] + AutoDiscovery --> FrameworkDetect[Detect framework:
package.json jest/vitest
requirements.txt pytest
go.mod built-in] + FrameworkDetect --> StructureScan[Scan test directory structure:
tests/e2e/, tests/integration/, tests/unit/] + StructureScan --> NamingDetect[Detect naming conventions:
*.test.js, *.spec.ts, test_*.py, *_test.go] + + NamingDetect --> ValidateReadme[Validate tests/README.md sections:
Test Organization, Running Tests] + + ValidateStrategy --> Summary + ValidateReadme --> Summary + + Summary[Display completion summary:
Files created/preserved,
Framework detected,
Structure validated] + + Summary --> End([End: ✓ Test docs created + validated]) + + %% Styling + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px + classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px + + class Phase1,CheckDirs,MakeDirs,CheckFiles,CreateFiles,Preserved,AutoFix,FrameworkDetect,StructureScan,NamingDetect,Summary action + class Phase2,Phase3,ValidateStrategy,AutoDiscovery,ValidateReadme validation + class CreateDirs,FilesExist decision +
+
+ +
+

🔑 Key Features

+
    +
  • Sixth Worker: Creates test documentation after presentation (ln-110 → ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116)
    • +
  • Two Files: testing-strategy.md (universal philosophy) + tests/README.md (organization with framework-specific details)
    • +
  • Universal Philosophy: testing-strategy.md is framework-agnostic (Risk-Based Testing, test pyramid, isolation patterns)
    • +
  • Story-Level Test Task Pattern: All tests consolidated in final Story task (NOT scattered across implementation tasks)
    • +
  • Framework Detection: Auto-discovers test framework from package.json/requirements.txt/go.mod
    • +
  • Structure Auto-Discovery: Scans tests/ directory for e2e/integration/unit, detects naming conventions
    • +
  • Idempotent: Checks file existence, preserves existing files, re-validates on each run
    • +
+
+ +
+

Generated for ln-116-test-docs-creator skill | Version 7.0.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-18

+
+
+ + + + diff --git a/skills/ln-116-test-docs-creator/references/questions.md b/skills/ln-116-test-docs-creator/references/questions.md new file mode 100644 index 0000000..34331ed --- /dev/null +++ b/skills/ln-116-test-docs-creator/references/questions.md @@ -0,0 +1,235 @@ +# Test Documentation Questions + +**Purpose:** Define what each section of test documentation should answer. + +**Format:** Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints + +--- + +## Table of Contents + +| Document | Questions | Auto-Discovery | Priority | Line | +|----------|-----------|----------------|----------|------| +| [docs/reference/guides/testing-strategy.md](#docsreferenceguidestesting-strategymd) | 2 | None | High | L25 | +| [tests/README.md](#testsreadmemd) | 2 | High | High | L101 | + +**Priority Legend:** +- **Critical:** Must answer all questions +- **High:** Strongly recommended +- **Medium:** Optional (can use template defaults) + +**Auto-Discovery Legend:** +- **None:** No auto-discovery needed (use template as-is) +- **Low:** 1-2 questions need auto-discovery +- **High:** All questions need auto-discovery + +--- + + +## docs/reference/guides/testing-strategy.md + +**File:** docs/reference/guides/testing-strategy.md (universal testing philosophy) +**Target Sections:** Testing Philosophy, Test Levels + +**Rules for this document:** +- Universal testing philosophy (NOT framework-specific) +- Risk-Based Testing principle +- Story-Level Test Task Pattern +- No auto-discovery needed (standard best practices) + +--- + + +### Question 1: What is the overall testing approach? + +**Expected Answer:** Risk-Based Testing principle, test pyramid levels (E2E/Integration/Unit), priority-driven approach (Priority ≥15) +**Target Section:** ## Testing Philosophy + +**Validation Heuristics:** +- ✅ Mentions "Risk-Based Testing" or "risk-based" +- ✅ Has test pyramid description (E2E, Integration, Unit) +- ✅ Mentions priority threshold (≥15 or "Priority 15") +- ✅ References "Story-Level Test Task Pattern" +- ✅ Length > 100 words + +**Auto-Discovery:** +- N/A (standard philosophy from template) + +**MCP Ref Hints:** +- Research: "risk-based testing best practices" (if template needs enhancement) +- Research: "test pyramid Martin Fowler" (if need to explain pyramid rationale) + + +--- + + +### Question 2: What are the test level targets? + +**Expected Answer:** E2E tests 2-5 per Story, Integration tests 3-8 per Story, Unit tests 5-15 per Story, rationale for each level +**Target Section:** ## Test Levels + +**Validation Heuristics:** +- ✅ Lists 3 levels: E2E, Integration, Unit +- ✅ Has numeric ranges: "2-5" for E2E, "3-8" for Integration, "5-15" for Unit +- ✅ Explains purpose/rationale for each level +- ✅ Total mentions "10-28 tests per Story" +- ✅ Length > 150 words + +**Auto-Discovery:** +- N/A (standard targets from template) + +**MCP Ref Hints:** +- Research: "testing pyramid ratios" (if need to justify ranges) +- Research: "value-based testing approach" (if need to explain priority-driven testing) + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tags in first 5 lines +- ✅ NO framework-specific code examples (FastAPI, pytest, Jest, etc.) +- ✅ Has Maintenance section at end +- ✅ Total length > 400 words + + + +--- + + +## tests/README.md + +**File:** tests/README.md (test organization structure) +**Target Sections:** Test Organization, Running Tests + +**Rules for this document:** +- Project-specific test organization +- Auto-discovery of test frameworks (Jest/Vitest/Pytest/Mocha) +- Auto-discovery of directory structure (e2e/, integration/, unit/) +- Auto-discovery of naming conventions +- Auto-discovery of test runner commands + +--- + + +### Question 3: How are tests organized in this project? + +**Expected Answer:** Directory structure (tests/e2e/, tests/integration/, tests/unit/), naming conventions (*.test.js or *.spec.js or test_*.py), Story-Level Test Task Pattern +**Target Section:** ## Test Organization + +**Validation Heuristics:** +- ✅ Describes directory structure with 3 levels (e2e, integration, unit) +- ✅ Mentions naming conventions (*.test.*, *.spec.*, test_*.*) +- ✅ References Story-Level Test Task Pattern +- ✅ Has test framework mention (Jest, Vitest, Pytest, Mocha, etc.) +- ✅ Length > 80 words + +**Auto-Discovery:** +1. **Scan tests/ directory:** + - Use Glob tool: `pattern: "tests/e2e/**/*.{js,ts,py,go}"` + - Use Glob tool: `pattern: "tests/integration/**/*.{js,ts,py,go}"` + - Use Glob tool: `pattern: "tests/unit/**/*.{js,ts,py,go}"` + - Count files in each directory + - Example output: "✓ Test structure: 12 E2E, 45 Integration, 78 Unit tests" + +2. **Detect test framework:** + - Check package.json → "devDependencies" or "dependencies": + - Node.js: jest, vitest, mocha, ava, tap, jasmine + - Extract version + - Check requirements.txt (if exists): + - Python: pytest, nose2, unittest2 + - Extract version + - Check go.mod (if exists): + - Go: testing (built-in) + - Example output: "✓ Test framework detected: jest@29.7.0" + +3. **Extract naming conventions:** + - For each test file found: + - Extract filename pattern: + - *.test.js → "*.test.js" convention + - *.spec.ts → "*.spec.ts" convention + - test_*.py → "test_*.py" convention + - *_test.go → "*_test.go" convention + - Use most common pattern (majority rule) + - Example output: "✓ Naming convention: *.test.js (detected from 135 files)" + +4. **If tests/ directory doesn't exist:** + - Create placeholder structure: + ``` + tests/ + e2e/ (empty, ready for E2E tests) + integration/ (empty, ready for Integration tests) + unit/ (empty, ready for Unit tests) + ``` + - Log: "⚠️ Test directory structure created (will be populated during Story test task execution)" + +**MCP Ref Hints:** +- Research: "[detected_framework] best practices" (e.g., "jest best practices 2024") +- Research: "[detected_framework] naming conventions" (if need to explain patterns) + + +--- + + +### Question 4: How do I run tests locally? + +**Expected Answer:** Test runner command (npm test, pytest, go test), run specific test files, run with coverage +**Target Section:** ## Running Tests + +**Validation Heuristics:** +- ✅ Has test runner command (npm test, yarn test, pytest, go test, etc.) +- ✅ Mentions coverage (--coverage, coverage report, etc.) +- ✅ Shows how to run specific tests +- ✅ Has examples with actual commands +- ✅ Length > 50 words + +**Auto-Discovery:** +1. **Extract test command from package.json:** + - Read package.json → "scripts" → "test" + - Extract command: + - "jest" → "npm test" (runs Jest) + - "vitest" → "npm test" (runs Vitest) + - "mocha" → "npm test" (runs Mocha) + - Custom script → use as-is + - Example output: "Test runner: npm test (runs jest)" + +2. **Extract coverage command (if exists):** + - Check package.json → "scripts": + - "test:coverage": "jest --coverage" + - "coverage": "vitest run --coverage" + - Example output: "Coverage: npm run test:coverage" + +3. **For Python projects:** + - Check for pytest.ini or pyproject.toml + - Default: "pytest" or "python -m pytest" + - Coverage: "pytest --cov=src" + +4. **For Go projects:** + - Default: "go test ./..." + - Coverage: "go test -cover ./..." + +5. **If no test script found:** + - Default based on detected framework: + - Jest → "npm test" + - Vitest → "npm test" + - Pytest → "pytest" + - Go → "go test ./..." + - Log: "⚠️ No test script found in package.json. Using default '[command]'." + +**MCP Ref Hints:** +- N/A (framework-specific, use detected framework docs) + + +--- + +**Overall File Validation:** +- ✅ Has SCOPE tags in first 5 lines +- ✅ Has link to testing-strategy.md in Quick Navigation section +- ✅ Has Maintenance section at end +- ✅ Total length > 100 words + + + +--- + +**Version:** 1.0.0 +**Last Updated:** 2025-11-18 \ No newline at end of file diff --git a/skills/ln-116-test-docs-creator/references/testing_strategy_template.md b/skills/ln-116-test-docs-creator/references/testing_strategy_template.md new file mode 100644 index 0000000..4b94d48 --- /dev/null +++ b/skills/ln-116-test-docs-creator/references/testing_strategy_template.md @@ -0,0 +1,465 @@ +# Testing Strategy + +Universal testing philosophy and strategy for modern software projects: principles, organization, and best practices. + +> **SCOPE:** Testing philosophy, risk-based strategy, test organization, isolation patterns, what to test. **NOT IN SCOPE:** Project structure, framework-specific patterns, CI/CD configuration, test tooling setup. + +## Quick Navigation + +- **Tests Organization:** [tests/README.md](../../tests/README.md) - Directory structure, Story-Level Pattern, running tests +- **Test Inventory:** [tests/unit/REGISTRY.md](../../tests/unit/REGISTRY.md), [tests/integration/REGISTRY.md](../../tests/integration/REGISTRY.md), [tests/e2e/REGISTRY.md](../../tests/e2e/REGISTRY.md) + +--- + +## Core Philosophy + +### Test YOUR Code, Not Frameworks + +**Focus testing effort on YOUR business logic and integration usage.** Do not retest database constraints, ORM internals, framework validation, or third-party library mechanics. + +**Rule of thumb:** If deleting your code wouldn't fail the test, you're testing someone else's code. + +### Examples + +| Verdict | Test Description | Rationale | +|---------|-----------------|-----------| +| ✅ **GOOD** | Custom validation logic raises exception for invalid input | Tests YOUR validation rules | +| ✅ **GOOD** | Repository query returns filtered results based on business criteria | Tests YOUR query construction | +| ✅ **GOOD** | API endpoint returns correct HTTP status for error scenarios | Tests YOUR error handling | +| ❌ **BAD** | Database enforces UNIQUE constraint on email column | Tests database, not your code | +| ❌ **BAD** | ORM model has correct column types and lengths | Tests ORM configuration, not logic | +| ❌ **BAD** | Framework validates request body matches schema | Tests framework validation | + +--- + +## Risk-Based Testing Strategy + +### Priority Matrix + +**Automate only high-value scenarios** using Business Impact (1-5) × Probability (1-5). + +| Priority Score | Action | Example Scenarios | +|----------------|--------|-------------------| +| **≥15** | MUST test | Payment processing, authentication, data loss scenarios | +| **10-14** | Consider testing | Edge cases with moderate impact | +| **<10** | Skip automated tests | Low-probability edge cases, framework behavior | + +### Test Caps (per Story) + +**Enforce caps to prevent test bloat:** + +- **E2E:** 2-5 tests +- **Integration:** 3-8 tests +- **Unit:** 5-15 tests +- **Total:** 10-28 tests per Story + +**Key principles:** +- **No minimum limits** - Can be 0 tests if no Priority ≥15 scenarios exist +- **No test pyramids** - Test distribution based on risk, not arbitrary ratios +- **Every test must add value** - Each test should validate unique Priority ≥15 scenario + +**Exception:** ML/GPU/Hardware-dependent workloads may favor more E2E (5-10), fewer Integration (2-5), minimal Unit (1-3) because behavior is hardware-dependent and mocks lack fidelity. Same 10-28 total cap applies. + +--- + +## Story-Level Testing Pattern + +### When to Write Tests + +**Consolidate ALL tests in Story's final test task** AFTER implementation + manual verification. + +| Task Type | Contains Tests? | Rationale | +|-----------|----------------|-----------| +| **Implementation Tasks** | ❌ NO tests | Focus on implementation only | +| **Final Test Task** | ✅ ALL tests | Complete Story coverage after manual verification | + +### Benefits + +1. **Complete context** - Tests written when all code implemented +2. **No duplication** - E2E covers integration paths, no need to retest same code +3. **Better prioritization** - Manual testing identifies Priority ≥15 scenarios before automation +4. **Atomic delivery** - Story delivers working code + comprehensive tests together + +### Anti-Pattern Example + +| ❌ Wrong Approach | ✅ Correct Approach | +|-------------------|---------------------| +| Task 1: Implement feature X + write unit tests
Task 2: Update integration + write integration tests
Task 3: Add logging + write E2E tests | Task 1: Implement feature X
Task 2: Update integration points
Task 3: Add logging
**Task 4 (Final): Write ALL tests (2 E2E, 3 Integration, 8 Unit)** | +| **Result:** Tests scattered, duplication, incomplete coverage | **Result:** Tests consolidated, no duplication, complete coverage | + +--- + +## Test Organization + +### Directory Structure + +``` +tests/ +├── e2e/ # End-to-end tests (full system, real services) +│ ├── test_user_journey.ext +│ └── REGISTRY.md # E2E test inventory +├── integration/ # Integration tests (multiple components, real dependencies) +│ ├── api/ +│ ├── services/ +│ ├── db/ +│ └── REGISTRY.md # Integration test inventory +├── unit/ # Unit tests (single component, mocked dependencies) +│ ├── api/ +│ ├── services/ +│ ├── db/ +│ └── REGISTRY.md # Unit test inventory +└── README.md # Test documentation +``` + +### Test Inventory (REGISTRY.md) + +**Each test category has REGISTRY.md** with detailed test descriptions: + +**Purpose:** +- Document what each test validates +- Track test counts per Epic/Story +- Provide navigation for test maintenance + +**Format example:** + +```markdown +# E2E Test Registry + +## Quality Estimation (Epic 6 - API-69) + +**File:** tests/e2e/test_quality_estimation.ext + +**Tests (4):** +1. **evaluate_endpoint_batch_splitting** - MetricX batch splitting (segments >128 split into batches) +2. **evaluate_endpoint_gpu_integration** - MetricX-24 GPU service integration +3. **evaluate_endpoint_error_handling** - Service timeout handling (503 status) +4. **evaluate_endpoint_response_format** - Response schema validation + +**Total:** 4 E2E tests | **Coverage:** 100% Priority ≥15 scenarios +``` + +--- + +## Test Levels + +### E2E (End-to-End) Tests + +**Definition:** Full system tests with real external services and complete data flow. + +**Characteristics:** +- Real external APIs/services +- Real database +- Full request-response cycle +- Validates complete user journeys + +**When to write:** +- Critical user workflows (authentication, payments, core features) +- Integration with external services +- Priority ≥15 scenarios that span multiple systems + +**Example:** User registration flow (E2E) vs individual validation function (Unit) + +### Integration Tests + +**Definition:** Tests multiple components together with real dependencies (database, cache, file system). + +**Characteristics:** +- Real database/cache/file system +- Multiple components interact +- May mock external APIs +- Validates component integration + +**When to write:** +- Database query behavior +- Service orchestration +- Component interaction +- API endpoint behavior (without external services) + +**Example:** Repository query with real database vs service logic with mocked repository + +### Unit Tests + +**Definition:** Tests single component in isolation with mocked dependencies. + +**Characteristics:** +- Fast execution (<1ms per test) +- No external dependencies +- Mocked collaborators +- Validates single responsibility + +**When to write:** +- Business logic validation +- Complex calculations +- Error handling logic +- Custom transformations + +**Example:** Validation function with mocked data vs endpoint with real database + +--- + +## Isolation Patterns + +### Pattern Comparison + +| Pattern | Speed | Complexity | Best For | +|---------|-------|------------|----------| +| **Data Deletion** | ⚡⚡⚡ Fastest | Simple | Default choice (90% of projects) | +| **Transaction Rollback** | ⚡⚡ Fast | Moderate | Transaction semantics testing | +| **Database Recreation** | ⚡ Slow | Simple | Maximum isolation paranoia | + +### Data Deletion (Default) + +**How it works:** +1. Create schema once at test session start +2. Delete data after each test +3. Drop schema at test session end + +**Benefits:** +- Fast (5-8s for 50 tests) +- Simple implementation +- Full isolation between tests + +**When to use:** Default choice for most projects + +### Transaction Rollback + +**How it works:** +1. Start transaction before each test +2. Run test code +3. Rollback transaction after test + +**Benefits:** +- Good for testing transaction semantics +- Faster than DB recreation + +**When to use:** Testing transaction behavior, savepoints, isolation levels + +### Database Recreation + +**How it works:** +1. Drop and recreate database before each test +2. Apply migrations +3. Run test + +**Benefits:** +- Maximum isolation +- Catches migration issues + +**When to use:** Paranoia about shared state, testing migrations + +--- + +## What To Test vs NOT Test + +### ✅ Test (GOOD) + +**Test YOUR code and integration usage:** + +| Category | Examples | +|----------|----------| +| **Business logic** | Validation rules, orchestration, error handling, computed properties | +| **Query construction** | Filters, joins, aggregations, pagination | +| **API behavior** | Request validation, response shape, HTTP status codes | +| **Custom validators** | Complex validation logic, transformations | +| **Integration smoke** | Database connectivity, basic CRUD, configuration | + +### ❌ Avoid (BAD) + +**Don't test framework internals and third-party libraries:** + +| Category | Examples | +|----------|----------| +| **Database constraints** | UNIQUE, FOREIGN KEY, NOT NULL, CHECK constraints | +| **ORM internals** | Column types, table creation, metadata, relationships | +| **Framework validation** | Request body validation, dependency injection, routing | +| **Third-party libraries** | HTTP client behavior, serialization libraries, cryptography | + +--- + +## Testing Patterns + +### Arrange-Act-Assert + +**Structure tests clearly:** + +``` +test_example: + # ARRANGE: Set up test data and dependencies + setup_data() + mock_dependencies() + + # ACT: Execute code under test + result = execute_operation() + + # ASSERT: Verify outcomes + assert result == expected + verify_side_effects() +``` + +**Benefits:** +- Clear test structure +- Easy to read and maintain +- Explicit test phases + +### Mock at the Seam + +**Mock at component boundaries, not internals:** + +| Test Type | What to Mock | What to Use Real | +|-----------|--------------|------------------| +| **Unit tests** | External dependencies (repositories, APIs, file system) | Business logic | +| **Integration tests** | External APIs, slow services | Database, cache, your code | +| **E2E tests** | Nothing (or minimal external services) | Everything | + +**Anti-pattern:** Over-mocking your own code defeats the purpose of integration tests. + +### Test Data Builders + +**Create readable test data:** + +``` +# Builder pattern for test data +user = build_user( + email="test@example.com", + role="admin", + active=True +) + +# Easy to create edge cases +inactive_user = build_user(active=False) +guest_user = build_user(role="guest") +``` + +**Benefits:** +- Readable test setup +- Easy edge case creation +- Reusable across tests + +--- + +## Common Issues + +### Flaky Tests + +**Symptom:** Tests pass/fail randomly without code changes + +**Common causes:** +- Shared state between tests (global variables, cached data) +- Time-dependent logic (timestamps, delays) +- External service instability +- Improper cleanup between tests + +**Solutions:** +- Isolate test data (per-test creation, cleanup) +- Mock time-dependent code +- Use test-specific configurations +- Implement proper teardown + +### Slow Tests + +**Symptom:** Test suite takes too long (>30s for 50 tests) + +**Common causes:** +- Database recreation per test +- Running migrations per test +- No connection pooling +- Too many E2E tests + +**Solutions:** +- Use Data Deletion pattern +- Run migrations once per session +- Optimize test data creation +- Balance test levels (more Unit, fewer E2E) + +### Test Coupling + +**Symptom:** Changing one component breaks many unrelated tests + +**Common causes:** +- Tests depend on implementation details +- Shared test fixtures across unrelated tests +- Testing framework internals instead of behavior + +**Solutions:** +- Test behavior, not implementation +- Use independent test data per test +- Focus on public APIs, not internal state + +--- + +## Coverage Guidelines + +### Targets + +| Layer | Target | Priority | +|-------|--------|----------| +| **Critical business logic** | 100% branch coverage | HIGH | +| **Repositories/Data access** | 90%+ line coverage | HIGH | +| **API endpoints** | 80%+ line coverage | MEDIUM | +| **Utilities/Helpers** | 80%+ line coverage | MEDIUM | +| **Overall** | 80%+ line coverage | MEDIUM | + +### What Coverage Means + +**Coverage is a tool, not a goal:** +- ✅ High coverage + focused tests = good quality signal +- ❌ High coverage + meaningless tests = false confidence +- ❌ Low coverage = blind spots in testing + +**Focus on:** +- Critical paths covered +- Edge cases tested +- Error handling validated + +**Not on:** +- Arbitrary percentage targets +- Testing getters/setters +- Framework code + +--- + +## Verification Checklist + +### Strategy + +- [ ] Risk-based selection (Priority ≥15) +- [ ] Test caps enforced (E2E 2-5, Integration 3-8, Unit 5-15) +- [ ] Total 10-28 tests per Story +- [ ] Tests target YOUR code, not framework internals +- [ ] E2E smoke tests for critical integrations + +### Organization + +- [ ] Story-Level Test Task Pattern followed +- [ ] Tests consolidated in final Story task +- [ ] REGISTRY.md files maintained for all test categories +- [ ] Test directory structure follows conventions + +### Isolation + +- [ ] Isolation pattern chosen (Data Deletion recommended) +- [ ] Each test creates own data +- [ ] Proper cleanup between tests +- [ ] No shared state between tests + +### Quality + +- [ ] Tests are order-independent +- [ ] Tests run fast (<10s for 50 integration tests) +- [ ] No flaky tests +- [ ] Coverage ≥80% overall, 100% for critical logic +- [ ] Meaningful test names and descriptions + +--- + +## Maintenance + +**Update Triggers:** +- New testing patterns discovered +- Framework version changes affecting tests +- Significant changes to test architecture +- New isolation issues identified + +**Verification:** Review this strategy when starting new projects or experiencing test quality issues. + +**Last Updated:** [CURRENT_DATE] - Initial universal testing strategy diff --git a/skills/ln-116-test-docs-creator/references/tests_readme_template.md b/skills/ln-116-test-docs-creator/references/tests_readme_template.md new file mode 100644 index 0000000..b1b0de4 --- /dev/null +++ b/skills/ln-116-test-docs-creator/references/tests_readme_template.md @@ -0,0 +1,114 @@ +# Test Documentation + +**Last Updated:** {{DATE}} + + + + +--- + +## Overview + +This directory contains all tests for the project, following the **Story-Level Test Task Pattern** where tests are consolidated in the final Story test task (NOT scattered across implementation tasks). + +**Test organization:** +- **E2E tests** (End-to-End) - 2-5 per Story - Priority ≥15 scenarios MUST be tested +- **Integration tests** - 3-8 per Story - Multi-component interactions +- **Unit tests** - 5-15 per Story - Individual component logic +- **Total**: 10-28 tests per Story (Value-Based Testing) + +--- + +## Testing Philosophy + +**Test YOUR code, not frameworks.** Focus on business logic and integration usage. Avoid testing database constraints, ORM internals, or framework validation. + +**Risk-based testing:** Automate only Priority ≥15 scenarios (Business Impact × Probability). Test caps prevent bloat: 2-5 E2E, 3-8 Integration, 5-15 Unit (10-28 total per Story). No minimum limits - can be 0 if no high-priority scenarios exist. + +**Rule of thumb:** If deleting your code wouldn't fail the test, you're testing someone else's code. + +👉 **Full strategy:** See [docs/reference/guides/testing-strategy.md](../docs/reference/guides/testing-strategy.md) + +--- + +## Test Structure + +``` +tests/ +├── e2e/ # End-to-End tests (2-5 per Story) +│ ├── auth/ +│ ├── user-flows/ +│ └── critical-paths/ +├── integration/ # Integration tests (3-8 per Story) +│ ├── api/ +│ ├── database/ +│ └── services/ +└── unit/ # Unit tests (5-15 per Story) + ├── components/ + ├── utils/ + └── services/ +``` + +--- + +## Story-Level Test Task Pattern + +**Rule**: All tests (E2E/Integration/Unit) are written in the **final Story test task** (created by ln-350-story-test-planner after manual testing). + +**Why**: +- **Single source of truth**: All Story tests in one place +- **Atomic completion**: Story Done when all tests pass +- **No scattered tests**: NOT in implementation tasks +- **Regression prevention**: Test suite runs before Story marked Done + +**Workflow**: +1. Implementation tasks completed → Manual testing → Bugs fixed +2. ln-350-story-test-planner creates Story Finalizer test task +3. ln-334-test-executor implements all tests (E2E/Integration/Unit) in final task +4. All tests pass → Story marked Done + +--- + +## Test Execution + +**Run all tests:** +```bash +npm test +``` + +**Run specific test suites:** +```bash +npm run test:unit # Unit tests only +npm run test:integration # Integration tests only +npm run test:e2e # E2E tests only +``` + +**Watch mode (development):** +```bash +npm run test:watch +``` + +--- + +## Quick Navigation + +- **Testing Strategy**: [docs/reference/guides/testing-strategy.md](../docs/reference/guides/testing-strategy.md) - Philosophy, risk-based strategy, what to test +- **Story test tasks**: [docs/tasks/kanban_board.md](../docs/tasks/kanban_board.md) - Story test task tracking +- **Story-Level Pattern**: [docs/tasks/README.md](../docs/tasks/README.md) - Full pattern explanation +- **Test guidelines**: [docs/reference/guides/](../docs/reference/guides/) - Additional testing best practices + +--- + +## Maintenance + +**Update Triggers**: +- When adding new test directories or test suites +- When changing test execution commands +- When modifying Story-Level Test Task Pattern workflow + +**Verification**: +- All test directories exist (e2e/, integration/, unit/) +- Test execution commands work correctly +- SCOPE tags correctly define test documentation boundaries + +**Last Updated**: {{DATE}} diff --git a/skills/ln-200-scope-decomposer/SKILL.md b/skills/ln-200-scope-decomposer/SKILL.md new file mode 100644 index 0000000..260033b --- /dev/null +++ b/skills/ln-200-scope-decomposer/SKILL.md @@ -0,0 +1,385 @@ +--- +name: ln-200-scope-decomposer +description: Orchestrates full decomposition (scope → Epics → Stories) by delegating ln-210 → ln-220. Sequential Story decomposition per Epic. Epic 0 for Infrastructure. +--- + +# Scope Decomposer (Top Orchestrator) + +Top-level orchestrator for complete initiative decomposition from scope to User Stories through Epic and Story coordinators. + +## Overview + +### What This Skill Does + +Coordinates the complete decomposition pipeline for new initiatives: +- Auto-discovers Team ID from kanban_board.md +- **Phase 1:** Discovery (Team ID) +- **Phase 2:** Epic Decomposition (delegates to ln-210-epic-coordinator) +- **Phase 3:** Story Decomposition Loop (delegates to ln-220-story-coordinator per Epic, sequential) +- **Phase 4:** Summary (total counts + next steps) + +### When to Use This Skill + +This skill should be used when: +- Start new initiative requiring full decomposition (scope → Epics → Stories) +- Automate Epic + Story creation in single workflow +- Prefer full pipeline over manual step-by-step invocation +- Time-efficient approach for new projects (2-3 hours end-to-end) + +**Alternative:** For granular control, invoke coordinators manually: +1. [ln-210-epic-coordinator](../ln-210-epic-coordinator/SKILL.md) - CREATE/REPLAN Epics +2. [ln-220-story-coordinator](../ln-220-story-coordinator/SKILL.md) - CREATE/REPLAN Stories (once per Epic) + +### When NOT to Use + +Do NOT use if: +- Initiative already has Epics → Use ln-210-epic-coordinator REPLAN mode instead +- Need to replan existing Stories → Use ln-220-story-coordinator REPLAN mode per Epic +- Only need Epic creation → Use ln-210-epic-coordinator directly +- Only need Story creation for specific Epic → Use ln-220-story-coordinator directly + +--- + +## Core Concepts + +### Orchestrator Pattern + +**ln-200-scope-decomposer is a pure coordinator** - it does NOT execute work directly: +- ✅ Discovers context (Team ID) +- ✅ Makes routing decisions (which coordinator to invoke) +- ✅ Delegates all work via Skill tool (ln-210, ln-220) +- ✅ Manages workflow state (Epic creation → Story loop) +- ❌ Does NOT research project docs (ln-210 does this) +- ❌ Does NOT generate Epic/Story documents (ln-210/ln-220 do this) +- ❌ Does NOT create Linear issues (coordinators do this) +- ❌ Does NOT prompt user (coordinators handle all user interaction) + +**Coordinators:** +- **ln-210-epic-coordinator:** Creates 3-7 Epics (Epic 0 for Infrastructure if applicable, Epic 1-N for business domains) +- **ln-220-story-coordinator:** Creates 5-10 Stories per Epic (with standards research via ln-221) + +### Sequential Story Decomposition + +**CRITICAL CONSTRAINT:** Epic N Stories MUST complete before Epic N+1 starts. + +**Why sequential?** +- ln-220-story-coordinator includes user interaction (Story preview confirmation) +- Interactive dialog cannot be parallelized (user must review each Epic's Stories) +- Ensures Epic N Stories are approved and created before starting Epic N+1 + +**Example:** 6 Epics → ln-220 invoked 6 times sequentially (Epic 0 → Epic 1 → Epic 2 → ... → Epic 5) + +### Infrastructure Epic = Epic 0 + +**Reserved number:** Epic 0 is reserved for Infrastructure Epic (if proposed by ln-210). + +**Numbering:** +- IF Infrastructure Epic exists → Epic 0 (Infrastructure), Epic 1-N (business domains) +- ELSE → Epic 1-N (business domains only) + +**Decision:** ln-210-epic-coordinator Phase 1 Step 3 automatically determines if Infrastructure Epic is needed (new project, multi-stack, security/monitoring requirements). + +### Auto-Discovery + +**Team ID**: Auto-discovered from `docs/tasks/kanban_board.md` Linear Configuration table (see CLAUDE.md "Configuration Auto-Discovery"). + +**Fallback:** If kanban_board.md missing → ln-210-epic-coordinator will ask user directly + +--- + +## Workflow + +### Phase 1: Discovery (Automated) + +Auto-discovers Team ID from `docs/tasks/kanban_board.md`. + +**Validation:** +- Team ID exists in kanban_board.md +- If missing → Skip (ln-210 will request from user) + +**NO user confirmation at orchestrator level** - coordinators handle all user interaction. + +**Output:** Team ID (or None if not found) + +### Phase 2: Epic Decomposition (Delegated) + +**Objective:** Create all Epics for initiative. + +Delegate to ln-210-epic-coordinator: +``` +🔄 [ORCHESTRATOR] Phase 2: Delegating Epic creation to ln-210-epic-coordinator + +Skill(skill: "ln-210-epic-coordinator") +``` + +**ln-210-epic-coordinator will:** +- Phase 1: Research project docs (requirements.md, architecture.md, tech_stack.md) +- Phase 2: Auto-propose domains + Infrastructure Epic (Epic 0) → User confirms domain list +- Phase 3: Build IDEAL Epic plan (Epic 0-N) +- Phase 5a: Auto-extract Q1-Q4 from docs → Generate ALL Epic documents → Show batch preview → User confirms → Create all Epics +- Return: Epic URLs + summary + +**After completion:** Epics created in Linear, kanban_board.md updated. + +**Output:** 3-7 Epics created (Epic 0 for Infrastructure if applicable, Epic 1-N for business domains) + +### Phase 3: Story Decomposition Loop (Sequential, Delegated) + +**Objective:** Create Stories for EACH Epic (sequential processing). + +**Sequential Loop Logic:** + +``` +FOR EACH Epic (Epic 0, Epic 1, ..., Epic N): + 1. Invoke ln-220-story-coordinator for current Epic + 2. Wait for completion + 3. Verify Stories created in kanban_board.md + 4. Move to next Epic +``` + +**Invocation per Epic:** +``` +🔄 [ORCHESTRATOR] Phase 3: Delegating Story creation for Epic N to ln-220-story-coordinator + +Skill(skill: "ln-220-story-coordinator", epic_number="Epic N") +``` + +**ln-220-story-coordinator will (per Epic):** +- Phase 1: Auto-extract Q1-Q6 from Epic + Fallback search (requirements.md, tech_stack.md) +- Phase 2: Research standards via ln-221-standards-researcher (auto) +- Phase 3: Build IDEAL Story plan (5-10 Stories) +- Phase 4a: Generate ALL Story documents → Show preview → User confirms → Create all Stories +- Return: Story URLs + summary + +**Sequential constraint explanation:** +- ln-220 includes user interaction (Story preview confirmation) +- Cannot parallelize - user must review each Epic's Stories sequentially +- Epic N Stories approved → Epic N+1 Stories generated + +**After each Epic:** Stories created in Linear, kanban_board.md updated. + +**Output:** 30-60 Stories total (5-10 per Epic × 3-7 Epics) + +### Phase 4: Summary and Next Steps + +**Objective:** Provide complete decomposition overview. + +``` +🔄 [ORCHESTRATOR] Phase 4: Full decomposition complete + +Initiative Decomposition Summary: +- Epics created: N Projects (Epic 0: Infrastructure [if exists], Epic 1-N: Business domains) +- Stories created: M Issues (breakdown per Epic) +- Location: docs/tasks/kanban_board.md + +Next Steps: +1. Run ln-320-story-validator to validate all Stories +2. Use ln-300-story-pipeline to process each Story (tasks → execution → Done) + OR use ln-310-story-decomposer to create tasks manually for each Story +``` + +**Output:** Summary message with full decomposition results + +--- + +## Critical Rules + +### 1. Pure Orchestrator Pattern + +**Orchestrator responsibilities:** +- ✅ Discovery (Team ID) +- ✅ Routing decisions (which coordinator to invoke, when) +- ✅ Sequential loop management (Epic 0 → Epic 1 → ... → Epic N) +- ✅ Summary aggregation (count Epics, Stories) + +**Coordinator responsibilities** (NOT orchestrator): +- ❌ Research project docs → ln-210 +- ❌ Auto-extract Epic/Story info → ln-210/ln-220 +- ❌ Generate Epic/Story documents → ln-210/ln-220 +- ❌ Create Linear issues → ln-210/ln-220 +- ❌ User interaction (confirmations) → ln-210/ln-220 + +### 2. Sequential Story Decomposition + +**HARD RULE:** Epic N Stories MUST complete before Epic N+1 starts. + +**Rationale:** ln-220 includes user interaction (Story preview confirmation). Interactive dialog cannot be parallelized. + +**Example:** 6 Epics → 6 sequential ln-220 invocations (Epic 0 → Epic 1 → ... → Epic 5) + +### 3. No User Prompts at Orchestrator Level + +**Orchestrator does NOT prompt user:** +- ❌ NO "Proceed with decomposition?" confirmation (redundant - coordinators already confirm) +- ❌ NO time estimates (misleading - actual time varies) +- ❌ NO Epic/Story previews (coordinators handle this) + +**All user interaction delegated to coordinators:** +- ln-210 Phase 2: Domain approval (USER CONTROL POINT 1) +- ln-210 Phase 5a: Epic batch preview (USER CONTROL POINT 2) +- ln-220 Phase 4a: Story preview per Epic (USER CONTROL POINT 3, N times) + +### 4. Epic 0 for Infrastructure + +**Reserved number:** Epic 0 is reserved for Infrastructure Epic. + +**Decision point:** ln-210-epic-coordinator Phase 1 Step 3 automatically determines if Infrastructure Epic needed. + +**Numbering:** Epic 0 (if Infrastructure), Epic 1-N (business domains) + +--- + +## Definition of Done + +Before completing work, verify ALL checkpoints: + +**✅ Team ID Discovered (Phase 1):** +- [ ] Team ID loaded from kanban_board.md OR skipped (ln-210 will request) + +**✅ Epic Decomposition Complete (Phase 2):** +- [ ] Delegated to ln-210-epic-coordinator +- [ ] 3-7 Epics created (Epic 0 for Infrastructure if applicable, Epic 1-N for business domains) +- [ ] Epic URLs returned +- [ ] Epics visible in kanban_board.md + +**✅ Story Decomposition Complete (Phase 3):** +- [ ] Delegated to ln-220-story-coordinator for EACH Epic (sequential) +- [ ] 5-10 Stories created per Epic +- [ ] Story URLs returned for each Epic +- [ ] All Stories visible in kanban_board.md (Backlog section) + +**✅ Summary Provided (Phase 4):** +- [ ] Total counts displayed (Epics, Stories, breakdown per Epic) +- [ ] kanban_board.md location shown +- [ ] Next steps provided (validation, task creation) + +**Output:** Summary message with full decomposition results (Epics + Stories per Epic) + +--- + +## Integration with Ecosystem + +### Called By + +Users directly: "Decompose initiative: [initiative name]" or "Create epics and stories for [project]" + +### Calls (via Skill tool) + +- **ln-210-epic-coordinator** (Phase 2) - CREATE mode (batch Epic creation with batch preview) +- **ln-220-story-coordinator** (Phase 3, sequential loop) - CREATE mode per Epic (Story creation with preview) + +### Downstream + +After ln-200-scope-decomposer completes: +- **ln-320-story-validator** - validates all created Stories before task creation +- **ln-300-story-pipeline** - processes each Story (tasks → execution → Done) + - OR **ln-310-story-decomposer** - creates tasks manually for each Story + +--- + +## Best Practices + +### Orchestrator Responsibilities + +**DO:** +- ✅ Auto-discover Team ID +- ✅ Delegate to coordinators +- ✅ Manage sequential loop (Epic 0 → Epic 1 → ... → Epic N) +- ✅ Aggregate summary (count Epics, Stories) + +**DON'T:** +- ❌ Research project docs (ln-210 does this) +- ❌ Generate documents (coordinators do this) +- ❌ Create Linear issues (coordinators do this) +- ❌ Prompt user (coordinators handle all interaction) + +### Coordinator Trust + +**Trust coordinator results:** Coordinators return summary, orchestrator doesn't re-verify. + +**Error handling:** If coordinator returns error, report to user and stop pipeline. + +### Sequential Processing + +**Epic creation first:** Phase 2 creates ALL Epics before Phase 3 starts (ensures Epic IDs available). + +**Story creation sequential:** Phase 3 processes Epics one-by-one (Epic N Stories → Epic N+1 Stories). + +**Rationale:** User interaction in ln-220 requires sequential processing (cannot parallelize confirmations). + +### Time Estimates + +**Realistic estimate:** 2-3 hours for full decomposition (6 Epics × 7 Stories avg = 42 Stories). + +**Breakdown:** +- Phase 2 (Epic creation): 30-45 min (batch preview reduces time) +- Phase 3 (Story creation): 1.5-2 hours (6 Epics × 15-20 min per Epic) +- Phase 4 (Summary): 2 min + +**Do NOT provide time estimates to user** - varies based on project complexity and user response time. + +--- + +## Example Usage + +**Request:** +``` +"Decompose initiative: E-commerce Platform" +``` + +**Execution:** + +1. **Phase 1: Discovery** + - Team ID loaded from kanban_board.md + +2. **Phase 2: Epic Decomposition** + - Invoke ln-210-epic-coordinator + - ln-210 creates 6 Epics: + - Epic 11 (Infrastructure Epic 0 pattern) + - Epic 12-16 (business domains) + - Output: 6 Epic URLs + +3. **Phase 3: Story Decomposition Loop (Sequential)** + - **Epic 11:** Invoke ln-220 → 6 Stories (US017-US022) + - **Epic 12:** Invoke ln-220 → 7 Stories (US023-US029) + - **Epic 13:** Invoke ln-220 → 5 Stories (US030-US034) + - **Epic 14:** Invoke ln-220 → 6 Stories (US035-US040) + - **Epic 15:** Invoke ln-220 → 7 Stories (US041-US047) + - **Epic 16:** Invoke ln-220 → 5 Stories (US048-US052) + - Output: 36 Stories total + +4. **Phase 4: Summary** + ``` + 🔄 [ORCHESTRATOR] Full decomposition complete + + Initiative: E-commerce Platform + - Epics created: 6 Projects (Epic 11: Infrastructure, Epic 12-16: Business domains) + - Stories created: 36 Issues + - Epic 11: 6 Stories + - Epic 12: 7 Stories + - Epic 13: 5 Stories + - Epic 14: 6 Stories + - Epic 15: 7 Stories + - Epic 16: 5 Stories + - Location: docs/tasks/kanban_board.md + + Next Steps: + 1. Run ln-320-story-validator to validate all Stories + 2. Use ln-300-story-pipeline to process each Story (tasks → execution → Done) + ``` + +**Result:** 6 Epics + 36 Stories created through full pipeline automation + +--- + +## Chat Output Prefix + +Use emoji prefix for visual differentiation: +- 🔄 [ORCHESTRATOR] - ln-200-scope-decomposer (top orchestrator) + +**Purpose:** Helps users track orchestrator progress when delegating to multiple coordinators. + +--- + +**Version:** 2.0.0 (BREAKING: Complete rewrite following ln-300 Pure Orchestrator Pattern. Removed Phase 1 User Confirmation. Removed false "AUTOMATIC" claims. Added Epic 0 for Infrastructure. Added Sequential Story Decomposition explanation. Added Critical Rules section. Realistic time estimates (2-3h). Removed REPLAN mode (not applicable to top orchestrator - use ln-210/ln-220 REPLAN modes instead).) +**Last Updated:** 2025-11-20 diff --git a/skills/ln-200-scope-decomposer/diagram.html b/skills/ln-200-scope-decomposer/diagram.html new file mode 100644 index 0000000..27fac00 --- /dev/null +++ b/skills/ln-200-scope-decomposer/diagram.html @@ -0,0 +1,151 @@ + + + + + + ln-200-scope-decomposer - State Diagram + + + + +
+
+

🔄 ln-200-scope-decomposer

+

Scope Decomposer (Top Orchestrator) - State Diagram v2.0.0

+
+ +
+

📋 Workflow Overview

+
    +
  • Purpose: Full decomposition: scope → Epics (ln-210) → Stories (ln-220 loop)
    • +
  • Pattern: Pure Orchestrator (only routing, no work execution)
    • +
  • Delegation: ln-210-epic-coordinator v7.0.0 → ln-220-story-coordinator v4.0.0 (sequential per Epic)
    • +
  • Output: 3-7 Epics (Epic 0: Infrastructure, Epic 1-N: Business) + 15-70 Stories (5-10 per Epic)
    • +
  • Time: 2-3 hours end-to-end
    • +
+
+ +
+
+
+ Discovery +
+
+
+ Delegation +
+
+
+ Loop Control +
+
+
+ Completion +
+
+ +
+
+graph TD + Start([Start: Decompose Initiative]) --> Phase1[Phase 1: Discovery
Auto-discover Team ID
from kanban_board.md] + + Phase1 --> Phase2[Phase 2: Epic Decomposition
Delegate to ln-210-epic-coordinator v7.0.0] + + Phase2 --> LN210[ln-210 executes:
- Research docs + HTML
- Build Epic list Epic 0-N
- User confirms structure
- Batch preview ALL Epics
- User confirms
- Create ALL in Linear] + + LN210 --> WaitEpics[Wait for Epic creation complete] + WaitEpics --> VerifyEpics[Verify: Epics in kanban_board.md
Epic 0: Infrastructure if applicable
Epic 1-N: Business domains] + + VerifyEpics --> Phase3[Phase 3: Story Decomposition Loop
Sequential per Epic] + + Phase3 --> LoopStart[FOR EACH Epic
Epic 0 → Epic 1 → ... → Epic N] + + LoopStart --> CurrentEpic[Current Epic: Epic X] + + CurrentEpic --> DelegateLN220[Delegate to ln-220-story-coordinator
for Epic X] + + DelegateLN220 --> LN220[ln-220 executes:
- Extract Epic info
- Fallback search if needed
- Research standards
- Generate Stories
- User confirms
- Create in Linear] + + LN220 --> WaitStories[Wait for Story creation complete] + WaitStories --> VerifyStories[Verify: Stories in kanban_board.md
5-10 Stories for Epic X] + + VerifyStories --> MoreEpics{More Epics
to process?} + MoreEpics -->|Yes| LoopStart + MoreEpics -->|No| Phase4[Phase 4: Summary] + + Phase4 --> CountTotal[Count total:
N Epics Epic 0-N
M Stories US001-USMMM] + + CountTotal --> ShowNext[Display next steps:
1. ln-320-story-validator
2. ln-300-story-pipeline
OR ln-310-story-decomposer] + + ShowNext --> End([End: Full Decomposition Complete]) + + %% Styling + classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px + classDef loop fill:#FFF9C4,stroke:#F57C00,stroke-width:2px + classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px + classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px + + class Phase1 discovery + class Phase2,Phase3,LN210,LN220,DelegateLN220,CurrentEpic,LoopStart loop + class MoreEpics decision + class WaitEpics,VerifyEpics,WaitStories,VerifyStories,Phase4,CountTotal,ShowNext action +
+
+ +
+

🔑 Key Features v2.0.0

+
    +
  • Pure Orchestrator Pattern: Does NOT execute work - only routing via Skill tool
    • +
  • NO Orchestrator-Level Confirmation: Coordinators (ln-210, ln-220) handle all user interaction
    • +
  • Epic 0 Reserved: Infrastructure Epic automatically proposed by ln-210 if needed
    • +
  • Sequential Story Decomposition: Epic N Stories MUST complete before Epic N+1 starts (user interaction cannot parallelize)
    • +
  • Batch Preview in ln-210: ALL Epics shown before creation (v7.0.0 feature)
    • +
  • Fallback Search in ln-220: Auto-extract from requirements.md, tech_stack.md before asking user (v2.1.0 feature)
    • +
+
+ +
+

📐 Phase Structure

+
    +
  • Phase 1: Discovery - Auto-discover Team ID from kanban_board.md (silent, no user prompt)
    • +
  • Phase 2: Epic Decomposition - Delegate to ln-210-epic-coordinator v7.0.0 (batch preview, Epic 0 if applicable)
    • +
  • Phase 3: Story Decomposition Loop - FOR EACH Epic (Epic 0 → Epic 1 → ... → Epic N), delegate to ln-220-story-coordinator v4.0.0 sequentially
    • +
  • Phase 4: Summary - Count total Epics + Stories, display next steps (validation → task creation)
    • +
+
+ +
+

⚙️ Orchestrator Responsibilities

+
    +
  • ✅ DOES: Discovery (Team ID), Routing decisions, Sequential loop management, Summary aggregation
    • +
  • ❌ DOES NOT: Research docs, Generate documents, Create Linear issues, Prompt user (delegated to coordinators)
    • +
+
+ +
+

🔗 Coordinator Details

+
    +
  • ln-210-epic-coordinator v7.0.0: Creates 3-7 Epics (Epic 0 Infrastructure + Epic 1-N Business). Batch preview ALL before creation. HTML research. User confirms twice (structure + batch preview).
    • +
  • ln-220-story-coordinator v4.0.0: Coordinator that delegates to ln-222-story-creator (CREATE mode) or ln-223-story-replanner (REPLAN mode). Creates 5-10 Stories per Epic. Fallback search chain (Epic → requirements.md → tech_stack.md). User confirms once (Story preview).
    • +
+
+ +
+

Generated for ln-200-scope-decomposer skill | Version 2.0.0

+

Diagram format: Mermaid.js | Last updated: 2025-11-20

+
+
+ + + + diff --git a/skills/ln-210-epic-coordinator/SKILL.md b/skills/ln-210-epic-coordinator/SKILL.md new file mode 100644 index 0000000..7b58eb6 --- /dev/null +++ b/skills/ln-210-epic-coordinator/SKILL.md @@ -0,0 +1,594 @@ +--- +name: ln-210-epic-coordinator +description: CREATE/REPLAN Epics from scope (3-7 Epics). Batch Preview + Auto-extraction. Decompose-First Pattern. Auto-discovers team ID. +--- + +# Epic Coordinator + +Universal Epic management coordinator that handles both creation and replanning through scope decomposition. + +## When to Use This Skill + +This skill should be used when: +- Start new scope/initiative requiring decomposition into multiple logical domains (CREATE mode) +- Break down large architectural requirement into Epics +- Update existing Epics when scope/requirements change (REPLAN mode) +- Rebalance Epic scopes within an initiative +- Add new Epics to existing initiative structure +- First step in project planning (scope → Epics → Stories → Tasks) +- Define clear scope boundaries and success criteria for each domain + +**Output:** 3-7 Linear Projects (logical domains/modules) + +## Core Concepts + +### Decompose-First Pattern + +**Key principle:** ALWAYS analyze scope and build IDEAL Epic plan FIRST, THEN check existing Epics to determine mode: +- **No existing Epics** → CREATE MODE (generate and create all Epics) +- **Has existing Epics** → REPLAN MODE (compare, determine operations: KEEP/UPDATE/OBSOLETE/CREATE) + +**Rationale:** Ensures consistent Epic decomposition based on current scope requirements, independent of existing Epic structure (which may be outdated or suboptimal). + +### Epic 0 Reserved for Infrastructure + +**Rule:** Epic 0 is a reserved index for Infrastructure Epic within an initiative. + +**When to use Epic 0:** +- New project requiring infrastructure setup +- Multi-stack project (Frontend + Backend on different stacks) +- Project with security/monitoring/deployment requirements + +**Epic indexes within initiative:** +- **Epic 0:** Infrastructure & Operations (if needed) +- **Epic 1, 2, 3, ... N:** Business domains + +**Linear Project Titles:** +- Use Next Epic Number from kanban_board.md for sequential numbering +- Example: Next Epic Number = 11 + - Epic 0 → Linear title: "Epic 11: Infrastructure & Operations" + - Epic 1 → Linear title: "Epic 12: User Management" + - Epic 2 → Linear title: "Epic 13: Product Catalog" + +**Important:** Epic 0/1/2 are initiative-internal indexes for organizing domains. Linear uses global Next Epic Number for project titles. + +--- + +## Workflow + +### Phase 1: Discovery & Research + +**Objective:** Gather all necessary context before Epic decomposition. + +**Step 1: Load Configuration** + +Auto-discovers Team ID and Next Epic Number from `docs/tasks/kanban_board.md`: +- **Team ID:** Reads Linear Configuration table → Fallback: Ask user directly +- **Next Epic Number:** Reads Next Epic Number field → Fallback: Ask user directly + +**Details:** See CLAUDE.md sections "Configuration Auto-Discovery" and "Linear Integration". + +**Step 2: Project Research** + +**Objective:** Research project documentation AND frontend code to understand context BEFORE asking user questions. + +**Process:** + +1. **Document Scan:** + - Use `Glob` to find: `docs/requirements.md`, `docs/architecture.md`, `docs/tech_stack.md` + - Use `Read` to load found documents + +2. **Frontend Code Scan (if applicable):** + - Use `Glob` to find: `**/*.html`, `src/**/*.html`, `public/**/*.html`, `templates/**/*.html` + - Use `Read` to load HTML files + - Extract functional domains from: + - **Navigation menus:** `