diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100644 index 0000000..3932801 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1 @@ +npm run format diff --git a/frameworks/GOLANG_CLI.md b/frameworks/GOLANG_CLI.md new file mode 100644 index 0000000..daa5f9e --- /dev/null +++ b/frameworks/GOLANG_CLI.md @@ -0,0 +1,406 @@ +# FRAMEWORK.md + +# AI Issue Publisher Framework + +## Purpose + +This document defines implementation constraints. + +PRODUCT_SPEC.md defines what must be built. + +FRAMEWORK.md defines how it must be built. + +Implementations must follow this document exactly. + +Do not replace technologies. + +Do not introduce alternatives. + +Do not redesign architecture. + +--- + +# Language + +Use: + +```text +Go >= 1.24 +``` + +Do not use: + +```text +Node.js +TypeScript +Python +Rust +PHP +Java +``` + +--- + +# Architecture Style + +Use: + +```text +Single Binary CLI +``` + +Requirements: + +- no backend service +- no database +- no web server +- no daemon process + +The application must execute as a standalone command-line tool. + +--- + +# CLI Framework + +Use: + +```text +github.com/spf13/cobra +``` + +Do not introduce additional CLI frameworks. + +--- + +# Clipboard + +Use: + +```text +golang.design/x/clipboard +``` + +Clipboard is the primary input source. + +Do not require file input for normal workflows. + +--- + +# Markdown Processing + +Use: + +```text +github.com/yuin/goldmark +``` + +Markdown must be parsed programmatically. + +Do not use regex-only parsing. + +--- + +# GitHub Integration + +Use: + +```text +GitHub REST API +``` + +Authentication: + +```text +AI_BACKLOG_TOKEN +``` + +Requirements: + +- token belongs to ai-backlog-bot +- issues must be created using ai-backlog-bot credentials +- GitHub must display ai-backlog-bot as issue author + +Do not use: + +```text +Current user credentials +``` + +Do not create issues as the publishing user. + +--- + +# Publisher Detection + +Publisher identity is informational only. + +Resolve publisher using: + +```text +gh api user +``` + +Fallback: + +```text +git config user.name +``` + +Publisher information must be stored inside issue metadata. + +Publisher identity must never be used for issue creation. + +--- + +# Repository Resolution + +Resolve repository from: + +```text +git remote get-url origin +``` + +Expected result: + +```text +owner/repository +``` + +If repository resolution fails: + +```text +abort operation +``` + +Do not request repository information interactively. + +--- + +# Configuration + +Configuration format: + +```text +YAML +``` + +Location: + +```text +~/.config/ai-issue/config.yaml +``` + +Configuration is optional for MVP. + +Environment variables are preferred for secrets. + +--- + +# Secrets + +Use: + +```text +AI_BACKLOG_TOKEN +``` + +Environment variable only. + +Never store tokens in: + +- repository +- source code +- configuration files + +--- + +# Commands + +## Create Issue + +Command: + +```bash +ai-issue +``` + +Supported workflow: + +```text +Clipboard +↓ +Parse +↓ +Preview +↓ +Confirm +↓ +Create Issue +``` + +--- + +## Doctor + +Command: + +```bash +ai-issue doctor +``` + +Checks: + +- clipboard support +- git repository +- GitHub connectivity +- AI_BACKLOG_TOKEN availability + +Doctor command must not modify state. + +--- + +# Directory Structure + +Use: + +```text +cmd/ + ai-issue/ + +internal/ + clipboard/ + github/ + markdown/ + metadata/ + repository/ + publisher/ + +tests/ +``` + +Avoid: + +```text +pkg/ +services/ +helpers/ +utils/ +common/ +shared/ +``` + +Create packages around responsibilities. + +--- + +# Error Handling + +Return explicit errors. + +Do not silently continue. + +Examples: + +```text +Clipboard is empty. +``` + +```text +Current directory is not a git repository. +``` + +```text +Issue title could not be determined. +``` + +```text +AI_BACKLOG_TOKEN is not configured. +``` + +--- + +# Testing + +Use: + +```text +Go standard testing package +``` + +Do not introduce testing frameworks. + +Test: + +- markdown parsing +- repository resolution +- metadata generation +- issue payload generation + +Mock external systems when appropriate. + +Do not require GitHub access for unit tests. + +--- + +# Distribution + +Distribution method: + +```text +GitHub Releases +``` + +Artifacts: + +```text +macOS +Linux +Windows +``` + +Produce standalone binaries. + +Do not require runtime dependencies other than Git and GitHub access. + +--- + +# Non-Goals + +Do not implement: + +- AI APIs +- ChatGPT integration +- Claude integration +- Gemini integration +- pull request creation +- commit creation +- Slack integration +- Jira integration +- analytics +- project management features + +These are outside the scope of the project. + +--- + +# Framework Invariants + +The following conditions must always hold: + +```text +Author != Publisher +``` + +```text +GitHub Author == ai-backlog-bot +``` + +```text +Publisher == informational metadata only +``` + +```text +Single Binary CLI +``` + +Any implementation that violates these invariants is incorrect. diff --git a/package-lock.json b/package-lock.json index ff6d82a..e8c3ff7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,14 @@ { - "name": "documents", + "name": "replworks-documents", "lockfileVersion": 3, "requires": true, "packages": { "": { + "name": "replworks-documents", "devDependencies": { "eslint-config-prettier": "^10.1.8", + "husky": "^9.1.7", + "lint-staged": "^17.0.7", "markdownlint-cli": "^0.48.0", "prettier": "^3.8.3" } @@ -294,6 +297,22 @@ "url": "https://github.com/sponsors/epoberezkin" } }, + "node_modules/ansi-escapes": { + "version": "7.3.0", + "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-7.3.0.tgz", + "integrity": "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==", + "dev": true, + "license": "MIT", + "dependencies": { + "environment": "^1.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/ansi-regex": { "version": "6.2.2", "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", @@ -307,6 +326,19 @@ "url": "https://github.com/chalk/ansi-regex?sponsor=1" } }, + "node_modules/ansi-styles": { + "version": "6.2.3", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz", + "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", @@ -370,6 +402,56 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/cli-cursor": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz", + "integrity": "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==", + "dev": true, + "license": "MIT", + "dependencies": { + "restore-cursor": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/cli-truncate": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-5.2.0.tgz", + "integrity": "sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "slice-ansi": "^8.0.0", + "string-width": "^8.2.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/cli-truncate/node_modules/string-width": { + "version": "8.2.1", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.1.tgz", + "integrity": "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-east-asian-width": "^1.5.0", + "strip-ansi": "^7.1.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/commander": { "version": "14.0.3", "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz", @@ -470,6 +552,13 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/emoji-regex": { + "version": "10.6.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz", + "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==", + "dev": true, + "license": "MIT" + }, "node_modules/entities": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", @@ -483,6 +572,19 @@ "url": "https://github.com/fb55/entities?sponsor=1" } }, + "node_modules/environment": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz", + "integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/escape-string-regexp": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", @@ -673,6 +775,13 @@ "node": ">=0.10.0" } }, + "node_modules/eventemitter3": { + "version": "5.0.4", + "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz", + "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==", + "dev": true, + "license": "MIT" + }, "node_modules/fast-deep-equal": { "version": "3.1.3", "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", @@ -797,6 +906,22 @@ "node": ">=10.13.0" } }, + "node_modules/husky": { + "version": "9.1.7", + "resolved": "https://registry.npmjs.org/husky/-/husky-9.1.7.tgz", + "integrity": "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==", + "dev": true, + "license": "MIT", + "bin": { + "husky": "bin.js" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/typicode" + } + }, "node_modules/ignore": { "version": "5.3.2", "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz", @@ -877,6 +1002,22 @@ "node": ">=0.10.0" } }, + "node_modules/is-fullwidth-code-point": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-5.1.0.tgz", + "integrity": "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-east-asian-width": "^1.3.1" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/is-glob": { "version": "4.0.3", "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", @@ -1037,6 +1178,48 @@ "uc.micro": "^2.0.0" } }, + "node_modules/lint-staged": { + "version": "17.0.7", + "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-17.0.7.tgz", + "integrity": "sha512-JrSobt+tW3rH8IOMi8tDZd3foorM5yPEkLD/V2NxobgHrFfHWGee4MOLVuZeScgxftEwbHrPHIFA/ZL+nUJeuA==", + "dev": true, + "license": "MIT", + "dependencies": { + "listr2": "^10.2.1", + "picomatch": "^4.0.4", + "string-argv": "^0.3.2", + "tinyexec": "^1.2.4" + }, + "bin": { + "lint-staged": "bin/lint-staged.js" + }, + "engines": { + "node": ">=22.22.1" + }, + "funding": { + "url": "https://opencollective.com/lint-staged" + }, + "optionalDependencies": { + "yaml": "^2.9.0" + } + }, + "node_modules/listr2": { + "version": "10.2.1", + "resolved": "https://registry.npmjs.org/listr2/-/listr2-10.2.1.tgz", + "integrity": "sha512-7I5knELsJKTUjXG+A6BkKAiGkW1i25fNa/xlUl9hFtk15WbE9jndA89xu5FzQKrY5llajE1hfZZFMILXkDHk/Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "cli-truncate": "^5.2.0", + "eventemitter3": "^5.0.4", + "log-update": "^6.1.0", + "rfdc": "^1.4.1", + "wrap-ansi": "^10.0.0" + }, + "engines": { + "node": ">=22.13.0" + } + }, "node_modules/locate-path": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", @@ -1054,6 +1237,79 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/log-update": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/log-update/-/log-update-6.1.0.tgz", + "integrity": "sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-escapes": "^7.0.0", + "cli-cursor": "^5.0.0", + "slice-ansi": "^7.1.0", + "strip-ansi": "^7.1.0", + "wrap-ansi": "^9.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/slice-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-7.1.2.tgz", + "integrity": "sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.1", + "is-fullwidth-code-point": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/slice-ansi?sponsor=1" + } + }, + "node_modules/log-update/node_modules/string-width": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz", + "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^10.3.0", + "get-east-asian-width": "^1.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/wrap-ansi": { + "version": "9.0.2", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz", + "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.1", + "string-width": "^7.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, "node_modules/markdown-it": { "version": "14.1.1", "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.1.tgz", @@ -1676,6 +1932,19 @@ ], "license": "MIT" }, + "node_modules/mimic-function": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/mimic-function/-/mimic-function-5.0.1.tgz", + "integrity": "sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/minimatch": { "version": "10.2.5", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz", @@ -1717,6 +1986,22 @@ "license": "MIT", "peer": true }, + "node_modules/onetime": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-7.0.0.tgz", + "integrity": "sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "mimic-function": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/optionator": { "version": "0.9.4", "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz", @@ -1873,6 +2158,30 @@ "node": ">=6" } }, + "node_modules/restore-cursor": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-5.1.0.tgz", + "integrity": "sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==", + "dev": true, + "license": "MIT", + "dependencies": { + "onetime": "^7.0.0", + "signal-exit": "^4.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/rfdc": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz", + "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==", + "dev": true, + "license": "MIT" + }, "node_modules/run-con": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/run-con/-/run-con-1.3.2.tgz", @@ -1914,6 +2223,36 @@ "node": ">=8" } }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/slice-ansi": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-8.0.0.tgz", + "integrity": "sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.3", + "is-fullwidth-code-point": "^5.1.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/chalk/slice-ansi?sponsor=1" + } + }, "node_modules/smol-toml": { "version": "1.6.1", "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz", @@ -1927,6 +2266,16 @@ "url": "https://github.com/sponsors/cyyynthia" } }, + "node_modules/string-argv": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz", + "integrity": "sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.6.19" + } + }, "node_modules/string-width": { "version": "8.1.0", "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.1.0.tgz", @@ -1973,6 +2322,16 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/tinyexec": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.4.tgz", + "integrity": "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, "node_modules/tinyglobby": { "version": "0.2.17", "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz", @@ -2050,6 +2409,58 @@ "node": ">=0.10.0" } }, + "node_modules/wrap-ansi": { + "version": "10.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-10.0.0.tgz", + "integrity": "sha512-SGcvg80f0wUy2/fXES19feHMz8E0JoXv2uNgHOu4Dgi2OrCy1lqwFYEJz1BLbDI0exjPMe/ZdzZ/YpGECBG/aQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.3", + "string-width": "^8.2.0", + "strip-ansi": "^7.1.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi/node_modules/string-width": { + "version": "8.2.1", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.1.tgz", + "integrity": "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-east-asian-width": "^1.5.0", + "strip-ansi": "^7.1.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/yaml": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", + "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", + "dev": true, + "license": "ISC", + "optional": true, + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + }, "node_modules/yocto-queue": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", diff --git a/package.json b/package.json index a4f4c2c..5bbee1e 100644 --- a/package.json +++ b/package.json @@ -6,10 +6,18 @@ "format:check": "prettier --check '**/*.md'", "format": "prettier --write '**/*.md'", "validate": "npm run lint && npm run format", - "fix": "npm run lint:fix && npm run format:fix" + "fix": "npm run lint:fix && npm run format:fix", + "prepare": "husky" + }, + "lint-staged": { + "*.{js,jsx,ts,tsx,json,css,md}": [ + "npm run format" + ] }, "devDependencies": { "eslint-config-prettier": "^10.1.8", + "husky": "^9.1.7", + "lint-staged": "^17.0.7", "markdownlint-cli": "^0.48.0", "prettier": "^3.8.3" } diff --git a/prompts/AI_MEMORY_PROMPT.md b/prompts/AI_MEMORY_PROMPT.md index c44b1ca..92d7bf7 100644 --- a/prompts/AI_MEMORY_PROMPT.md +++ b/prompts/AI_MEMORY_PROMPT.md @@ -1,4 +1,4 @@ -# AI_MEMORY_PROMPT.md +# AI Memory Prompt Generate AI_MEMORY.md from this conversation. diff --git a/prompts/ARCHITECTURE_PROMPT.md b/prompts/ARCHITECTURE_PROMPT.md new file mode 100644 index 0000000..ebe204f --- /dev/null +++ b/prompts/ARCHITECTURE_PROMPT.md @@ -0,0 +1,63 @@ +# ARCHITECTURE_PROMPT.md + +Generate ARCHITECTURE.md. + +Assume PRODUCT_SPEC.md already exists and is correct. + +The purpose of ARCHITECTURE.md is to define: + +```text +How the product works internally. +How responsibilities are separated. +How information flows through the system. +Which invariants must always remain true. +``` + +Do not describe implementation technologies. + +Do not describe frameworks. + +Do not describe programming languages. + +Do not describe libraries. + +Do not describe deployment. + +Do not describe coding conventions. + +Architecture must remain technology-agnostic. + +The document must include: + +- Purpose +- Core Concepts +- System Flow +- Components +- Component Responsibilities +- Responsibility Boundaries +- Data Flow +- Architectural Rules +- Failure Boundaries +- Non-Goals +- Architectural Invariants + +Every component must have: + +- Responsibilities +- Inputs +- Outputs +- Explicit ownership boundaries + +Identify: + +- missing responsibilities +- conflicting responsibilities +- ambiguous flows + +Resolve them before generating the document. + +Prefer clear ownership over abstraction. + +Optimize for implementation certainty. + +The document is intended for AI implementation, not human documentation. diff --git a/prompts/FRAMEWORK_PROMPT.md b/prompts/FRAMEWORK_PROMPT.md new file mode 100644 index 0000000..8c9cbee --- /dev/null +++ b/prompts/FRAMEWORK_PROMPT.md @@ -0,0 +1,36 @@ +# GOLANG Cli Prompt + +Generate FRAMEWORK.md. + +Assume all technology decisions have already been made. + +Do not evaluate alternatives. + +Do not compare frameworks. + +Do not recommend different technologies. + +Generate an AI-oriented FRAMEWORK.md that constrains implementation. + +The document must: + +- define implementation rules +- define architectural constraints +- define directory structure +- define testing rules +- define deployment rules +- define configuration rules +- define security rules +- define framework-specific conventions +- define non-goals +- define architectural invariants + +Optimize for implementation consistency. + +The purpose of FRAMEWORK.md is to eliminate implementation ambiguity. + +If a decision has already been made, encode it as a rule. + +Prefer explicit constraints over explanations. + +The document is intended for AI implementation, not human learning. diff --git a/prompts/IDEAS_PROMPT.md b/prompts/IDEAS_PROMPT.md new file mode 100644 index 0000000..532184a --- /dev/null +++ b/prompts/IDEAS_PROMPT.md @@ -0,0 +1,31 @@ +# Ideas Prompt + +Generate IDEAS.md from this conversation. + +This document is intended for human consumption. + +Record only information explicitly discussed during the conversation. + +Do not expand the idea. + +Do not invent features. + +Do not invent business models. + +Do not invent technical solutions. + +Do not invent implementation details. + +Do not add assumptions. + +Do not add recommendations. + +Do not add future possibilities unless explicitly discussed. + +Preserve the original intent. + +Focus on capturing the idea exactly as discussed. + +If information was not mentioned in the conversation, omit it. + +Optimize for accurate idea preservation rather than idea improvement. diff --git a/prompts/PITCHING_SCRIPT_PROMPT.md b/prompts/PITCHING_SCRIPT_PROMPT.md new file mode 100644 index 0000000..332483b --- /dev/null +++ b/prompts/PITCHING_SCRIPT_PROMPT.md @@ -0,0 +1,37 @@ +# Pitching Script Prompt + +Generate PITCHING_SCRIPT.md from: + +- IDEAS.md +- this conversation + +Target Audience: + + + +This document is intended for human consumption. + +The goal is persuasion. + +Use information explicitly discussed during the conversation. + +You may expand: + +- market opportunity +- target users +- business potential +- revenue potential +- competitive advantages +- growth opportunities + +Only when they are supported by the conversation context. + +Do not invent unrealistic claims. + +Do not invent unsupported numbers. + +Clearly distinguish assumptions from established facts. + +Optimize for credibility, persuasion, and audience relevance. + +Adapt the structure and messaging for the target audience. diff --git a/prompts/PRODUCT_SPEC_PROMPT.md b/prompts/PRODUCT_SPEC_PROMPT.md new file mode 100644 index 0000000..2c9750c --- /dev/null +++ b/prompts/PRODUCT_SPEC_PROMPT.md @@ -0,0 +1,63 @@ +# PRODUCT_SPEC_PROMPT.md + +Generate PRODUCT_SPEC.md. + +Assume all product discovery and idea validation are already complete. + +The purpose of PRODUCT_SPEC.md is to define: + +```text +What the product is. +What the product does. +What the user can do. +What success means. +``` + +Do not describe implementation. + +Do not describe architecture. + +Do not describe technologies. + +Do not describe frameworks. + +Do not describe programming languages. + +Do not describe databases. + +Do not describe APIs. + +Do not describe internal components. + +Do not describe directory structures. + +Focus only on externally observable product behavior. + +The document should be sufficient for a product manager to approve the product scope. + +The document must include: + +- Purpose +- Problem +- Product Goals +- Users +- Inputs +- Outputs +- Functional Requirements +- User Flows +- Error Conditions +- Non-Goals +- Acceptance Criteria +- Success Criteria + +Do not propose improvements. + +Do not add features that were not discussed. + +Do not expand the scope. + +Prefer explicit requirements over explanations. + +Optimize for implementation certainty. + +The document is intended for AI implementation, not human marketing. diff --git a/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md new file mode 100644 index 0000000..873dd6e --- /dev/null +++ b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md @@ -0,0 +1,59 @@ +# REVIEW_IMPLEMENTATION_READINESS_PROMPT.md + +Review the following documents together: + +- PRODUCT_SPEC.md +- ARCHITECTURE.md +- FRAMEWORK.md + +Assume you are responsible for implementing the entire product. + +Assume no additional information will be provided. + +Your goal is to determine whether implementation can begin with confidence. + +Generate only questions. + +Do not answer questions. + +Do not suggest improvements. + +Do not suggest new features. + +Do not redesign the product. + +Do not modify requirements. + +Focus on identifying: + +- missing requirements +- missing architectural responsibilities +- missing implementation constraints +- ambiguous behavior +- conflicting definitions +- undefined ownership +- undefined flows +- undefined inputs +- undefined outputs +- contradictions between documents + +Treat the three documents as a single implementation contract. + +A question is valid only if it blocks implementation certainty. + +Ignore: + +- personal preferences +- alternative technologies +- feature ideas +- product strategy + +Output only a numbered list of questions. + +If no blocking questions exist, output: + +```text +Implementation can begin with high confidence. +``` + +Optimize for implementation certainty. diff --git a/prompts/TASKS_PROMPT.md b/prompts/TASKS_PROMPT.md new file mode 100644 index 0000000..d296803 --- /dev/null +++ b/prompts/TASKS_PROMPT.md @@ -0,0 +1,71 @@ +# TASKS_PROMPT.md + +Generate TASKS.md. + +Assume PRODUCT_SPEC.md exists. + +Assume ARCHITECTURE.md exists. + +Assume FRAMEWORK.md exists. + +The purpose of TASKS.md is to define: + +```text +What remains to be implemented. +``` + +TASKS.md is an execution checklist. + +Do not describe architecture. + +Do not describe technologies. + +Do not describe frameworks. + +Do not describe implementation details. + +Do not reference specific classes. + +Do not reference specific files. + +Do not reference specific libraries. + +Generate implementation tasks only. + +Tasks should represent user-visible capabilities or architectural milestones. + +Each task must be independently completable. + +Each task must be independently testable. + +Organize tasks into phases. + +For each phase: + +- define tasks +- define acceptance criteria + +Tasks must: + +- be actionable +- be verifiable +- be implementation-independent + +Avoid: + +- implementation steps +- code-level instructions +- framework-specific instructions + +Include: + +- MVP +- Future + +Acceptance criteria must be objective. + +A task is complete only when acceptance criteria are satisfied. + +Optimize for autonomous execution by AI systems. + +The document is intended for AI implementation, not human project management.