prompt-guide-cli 1.0.0

package/docs/request-guide.md

@@ -0,0 +1,157 @@
+# Request list writing guide
+
+How to **phrase requests** when asking the AI to do work: per-preset tips, how to fill `prompts/guide.template.yml`, and spec/ticket-style requests for the **implement** preset.
+
+---
+
+## Table of contents
+
+- [Request writing principles](#request-writing-principles)
+- [Per-preset request tips](#per-preset-request-tips)
+- [Template field guide (guide.template.yml)](#template-field-guide-guidetemplateyml)
+- [Spec / ticket writing (for implement)](#spec--ticket-writing-for-implement)
+- [Examples](#examples)
+
+---
+
+## Request writing principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Use clear verbs** | Be specific about what to do (e.g. “Add API call on login button click”, “Add null check in this function”) rather than “add something” or “fix it”. |
+| **Limit scope** | One logical task per request. Split large work into steps. |
+| **Give context** | When useful: file path/line, stack/platform, which rules to follow (e.g. platform rules). |
+| **Specify output format** | Saying “code only”, “explanation + code”, or “checklist then code” helps. |
+
+---
+
+## Per-preset request tips
+
+**task_presets** in `ai.config.yml` change which rules the AI uses. Use the following when phrasing requests.
+
+### default — General coding / editing
+
+- **When to use**: Routine edits, small improvements, behavior-only changes without refactor.
+- **How to request**: Name **target (file/function) + task**, e.g. “In this file change ~ to ~”, “Add ~ feature”.
+
+### implement — Implement from spec / ticket
+
+- **When to use**: Implementing a **new feature exactly as specified** in a spec or ticket.
+- **How to request**: Paste the **spec/ticket body** or write “Implement the following spec” plus conditions, I/O, and exceptions.
+- **Rule of thumb**: Request tests or a test plan as well.
+
+### refactor — Refactoring
+
+- **When to use**: Changing structure/style only; behavior stays the same.
+- **How to request**: Explicitly say **behavior must not change**, e.g. “Refactor only ~ without changing behavior”, “Split this module into ~”.
+
+### fix_bug — Bug fix
+
+- **When to use**: **Minimal fix** after finding the cause.
+- **How to request**: Describe what happens and expected behavior, e.g. “When ~, ~ happens. Find the cause and fix with minimal change.” Include repro steps if possible.
+
+### review — Code review
+
+- **When to use**: Reviewing a diff/PR.
+- **How to request**: “Review this change” or “Apply the checklist (consistency, quality, security, errors, compatibility) to the diff below and give approve / request-changes”.
+
+---
+
+## Template field guide (guide.template.yml)
+
+`prompts/guide.template.yml` defines **structured fields** for task prompts. Copy it, fill the values, and combine them in the `prompt_example` format before sending to the AI.
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **platform** | Target platform. | `iOS`, `Web`, `Server` |
+| **role** | One-line role for the AI. | “Modify the iOS app in this repo” |
+| **context.project** | Project/app name and purpose. | “Member login iOS app” |
+| **context.path** | Paths to work in. | `ios/App/`, `src/features/auth/` |
+| **context.stack** | Stack in use. | “SwiftUI, Combine” / “React, TypeScript” |
+| **context.rules_ref** | Rules to follow. | “rules.by-platform iOS block” |
+| **task** | What to do. **Use a clear verb.** | “Show error message in a toast on login failure” |
+| **constraints** | Optional constraints. | [“Keep existing API signatures”, “Add tests”] |
+| **output.format** | Output format. | “code only” / “explanation + code” / “checklist then code” |
+| **output.include** | What to include in output. | “Usage, how to test, caveats” |
+| **example** | Optional example. | Existing code snippet or similar screen |
+
+**Example** (after filling fields):
+
+```
+Platform: iOS
+Role: Modify the iOS app in this repo
+Context: Project member app, path ios/App/, stack SwiftUI. Rules: rules.by-platform iOS block
+Task: Show error message in a toast on login failure
+Constraints: Keep existing API signatures, add tests
+Output: format explanation+code, include usage and how to test
+Example: (if any)
+```
+
+---
+
+## Spec / ticket writing (for implement)
+
+For the **implement** preset, a short spec or ticket works well.
+
+| Item | Content |
+|------|---------|
+| **Summary** | One line: what you’re building. |
+| **Conditions / input** | When it runs (e.g. “On login failure”, “When this API returns 401”). |
+| **Expected behavior** | What should happen from the user/system perspective. |
+| **Constraints** | Must-haves (e.g. keep existing API, use specific library). |
+| **Tests** | “Add unit tests” or “Verify manually with this scenario”. |
+
+For long specs, paste the body and add one line like “Implement the above spec. Add tests.”
+
+---
+
+## Examples
+
+### 1. implement — Single feature
+
+```
+[Select implement preset]
+
+Implement the following:
+
+- Summary: Show error message in a toast when login fails
+- Condition: When AuthAPI returns 401 or an error message
+- Expected: Toast at bottom with server message, auto-dismiss after 3s
+- Constraints: Keep existing LoginView structure, reuse existing API call code
+- Tests: One unit test for the failure scenario
+```
+
+### 2. refactor — Refactor only
+
+```
+[Select refactor preset]
+
+Without changing behavior, refactor ios/App/Login/LoginViewModel.swift
+into separate methods for: network call, state, input validation.
+Ensure existing tests still pass.
+```
+
+### 3. fix_bug — Minimal fix
+
+```
+[Select fix_bug preset]
+
+App sometimes crashes when going to home after login. Find the cause and fix with minimal change.
+Repro: Login success → tap Home tab (roughly 10% of the time).
+```
+
+### 4. Using guide.template — Single block
+
+```
+Platform: Web
+Role: Modify the frontend in this repo
+Context: Project dashboard, path src/features/dashboard/, stack React + TypeScript
+Task: Add an “today’s tasks” count badge at the top of the dashboard (use existing API /tasks/count)
+Constraints: Reuse existing components, keep a11y
+Output: explanation + code, include usage and how to test
+```
+
+---
+
+This guide works best **together with** the prompt rules (system.core, review, rules-by-platform).  
+See [system.core.md](system.core.md), [review.md](review.md), and [rules-by-platform.md](rules-by-platform.md) for rule summaries.

package/docs/review.md

@@ -0,0 +1,34 @@
+# Code Review — Review criteria (human-readable)
+
+The actual text used for injection is in **YAML**.  
+→ `prompts/review.yml` (tools use the `prompt` key)
+
+---
+
+## Scope
+
+- **When used**: This prompt is used from `ai.config.yml`’s `prompts.review` and from `task_presets.review` and `task_presets.security_audit`. Use it for code review and security audits.
+
+## Review scope
+
+Review **all** of: full diff, new dependencies, config and env changes.
+
+## Checklist (report only violations as file:line + concrete issue)
+
+1. **Consistency**: Matches existing naming, style, layout, patterns, and platform conventions. Call out any mismatch.
+2. **Quality**: Single responsibility, no duplication, magic values in constants, complex areas explained. Request changes if not met.
+3. **Security**: No secrets/keys/tokens in code or logs; input validation (type, range, format) present. Request changes on violation.
+4. **Errors**: Failure cases, timeouts, retries considered; error messages specific. Call out if missing.
+5. **Compatibility**: No breaking existing API/behavior; migration or config changes documented when needed. Request changes if broken or undocumented.
+
+## Output format
+
+- **Summary**: 1–2 sentences (Approve / Conditional approve / Request changes).
+- **Per item**: Only violated items, in the order above, as **file:line + concrete description**.
+- **Suggestions**: Code snippets or steps when you have a fix to suggest.
+- **What’s good**: 1–2 lines (recommended).
+
+## Conclusion rules
+
+- **Any item not satisfied** → “Request changes”.
+- **All items satisfied** → “Approve”.

package/docs/rules-by-platform.md

@@ -0,0 +1,44 @@
+# Per-platform rules (human-readable)
+
+The actual text used for injection is in **YAML**.  
+→ `prompts/rules.by-platform.yml` (tools use `platforms.<name>.prompt`)
+
+- **When applied**: When `platform` in `ai.config.yml` is set to ios, android, flutter, web, or server, that platform’s block is merged after the system role. If `platform: null`, these rules are not applied.
+- **When forking**: Use only the blocks for your target platform(s); merge blocks if the project spans multiple platforms.
+
+---
+
+## iOS (Swift / SwiftUI / UIKit)
+
+- Follow project style for Swift naming, indentation, optionals, and error handling. Keep Podfile, SPM, or Carthage lock; do not change versions arbitrarily.
+- Consider accessibility (VoiceOver, Dynamic Type), dark mode, and localization. **UI updates on main thread only.**
+- Do not store secrets in code or plist. Use Keychain or env only. No PII or tokens in logs.
+
+## Android (Kotlin / Java)
+
+- Follow Kotlin/Java conventions and package layout. Keep Gradle and version catalog in sync; do not change versions arbitrarily.
+- Consider a11y (contentDescription, TalkBack), settings, localization, themes. **UI work on Main dispatcher only.**
+- Do not store secrets in code or resources. Use Keystore, BuildConfig, or env. No PII in logs or crash reports.
+
+## Flutter (Dart)
+
+- Follow effective_dart and project analysis options. Keep pubspec.lock and version ranges; do not change arbitrarily.
+- Consider accessibility (Semantics, labels), responsive layout, localization. Use async/await and Future for async; **keep build synchronous.**
+- Do not store secrets in code. Use flutter_dotenv, --dart-define, or native secrets. No secrets or PII in logs.
+
+## Web (JS/TS · React/Vue/Svelte etc.)
+
+- Follow project framework, bundler, and lint rules. Keep package-lock, yarn.lock, or pnpm-lock; do not change arbitrarily.
+- Consider a11y (semantics, ARIA, keyboard, focus), responsive layout, i18n. Keep CSR/SSR and hydration consistent.
+- Do not ship secrets in client code or build output. Use env or build-time injection. Consider XSS, CORS, CSP. No PII in logs or errors.
+
+## Server (Node/Go/Rust/Java/Python etc.)
+
+- Follow project conventions and directory layout. Keep lockfile, go.sum, Cargo.lock, requirements.txt, etc.; do not change arbitrarily.
+- Use a consistent API response shape (e.g. `{ success, data?, error? }`). Apply HTTP 2xx/4xx/5xx, timeouts, rate limits. Long work in queue/background only.
+- Do not store secrets in code. Use env or a secret manager. Do not skip input validation, auth, or authorization. No secrets or PII in logs.
+
+## Common (all platforms)
+
+- Add **unit tests** for public API and utilities. Test names: “condition → expected”. Mock only external dependencies.
+- Commits: “verb + object”. **One commit = one logical change.** PRs must state reason, how to test, and whether there are breaking changes.

package/docs/system.core.md

@@ -0,0 +1,54 @@
+# System Core — Core rules (human-readable)
+
+The actual text used for injection is in **YAML**.  
+→ `prompts/system.core.yml` (tools use the `prompt` key)
+
+---
+
+## Scope
+
+- **When applied**: This rule set is injected as the system role from `ai.config.yml`’s `system_role`, `prompts.default`, and most `task_presets` (default, refactor, implement, fix_bug, etc.). Review-only presets (review, security_audit) use `prompts/review.yml` instead.
+- **Audience**: All platforms (iOS, Android, Flutter, Web, Server). Language and framework neutral.
+
+## Role and response
+
+- Understand the request and **only provide actionable results** that fit the context.
+- For ambiguous requirements, pick **one** reasonable interpretation, state it, then proceed.
+- Structure responses (steps, code blocks, file:line references). When suggesting alternatives, give a one-line recommendation and reason.
+
+## Code quality
+
+- **Naming**: Make intent clear. No magic numbers/strings — use constants or config.
+- **Style**: **Keep existing** indentation, quotes, naming, and directory layout 100%. New code must follow existing patterns.
+- **Single responsibility**: One role per function/class. Split when violated.
+- **Duplication**: No repeated logic — extract to functions, utils, or shared components.
+- **Dependencies**: Minimize. Respect the platform lockfile; do not change versions arbitrarily.
+
+## Security
+
+- **Do not** put secrets, keys, or tokens in code, commits, or comments. Use env or a secret manager only.
+- Validate user and external input (**type, length, range, format, allow-list**) before use. Do not skip validation.
+- **Do not** include secrets or PII in logs, errors, or responses.
+
+## Errors and robustness
+
+- **Always consider** failure cases: network, files, API, bad input, timeouts.
+- Error messages must be specific enough to debug; include stack/code location when possible.
+- If retry, fallback, or partial success is possible, state and implement it.
+
+## Documentation and maintenance
+
+- Comments explain **why** only; **what** should be clear from names and structure. Comment complex logic and business rules.
+- Document public APIs (purpose, arguments, return value, exceptions; e.g. docstrings, OpenAPI).
+- **Do not** make breaking or behavior changes without checking call sites and compatibility.
+
+## Collaboration and checks
+
+- Respond in the user’s language. Follow project conventions for code and variable names.
+- When referring to code, give **path + line**.
+- Before submitting: style match, error handling, no secrets, tests/validation, existing behavior preserved. **If any is missing, fix before submitting.**
+
+## Exceptions
+
+Only relax or skip a rule when the user **explicitly** says so (e.g. “ignore style for this edit”).  
+Without that, all rules above apply.

package/docs/what-install.md

@@ -0,0 +1,114 @@
+# What Installs What — Feature overview
+
+This document explains **what each part** (CLI, config, presets, platforms) **adds** and **what to change when** you need to adjust behavior.  
+The same structure works for **any project** (language and framework agnostic).
+
+**CLI details**: see [docs/CLI.md](CLI.md).
+
+---
+
+## 0. CLI command summary
+
+| Command | Description |
+|---------|-------------|
+| `prompt-guide init` | Install ai/, prompts/, docs/ in the current directory and add platform-specific .gitignore. Use `-p <platform>` or interactive choice. |
+| `prompt-guide init --dry-run` | Show what would be done without writing files. |
+| `prompt-guide doctor` | Check presence and validity of ai/, config, prompts/, docs/, .gitignore. |
+| `prompt-guide doctor --fix` | Create or append the prompt-guide block in .gitignore when missing. |
+
+---
+
+## 1. What gets added on install (CLI `init` or manual copy)
+
+| Path | Description | Added by |
+|------|-------------|----------|
+| **ai/ai.config.yml** | Model, context, system role, task presets, platform, rules. **Single source of behavior.** | CLI init / manual copy |
+| **prompts/system.core.yml** | Core rules (YAML). Tools inject the `prompt` key. | CLI init / manual copy |
+| **prompts/review.yml** | Review rules. Uses `prompt` key. | CLI init / manual copy |
+| **prompts/rules.by-platform.yml** | Per-platform rules (ios, android, flutter, web, server, common). `platforms.<name>.prompt` | CLI init / manual copy |
+| **prompts/guide.template.yml** | Task prompt template field definitions. | CLI init / manual copy |
+| **docs/system.core.md** | Core rules summary (human-readable). | CLI init / manual copy |
+| **docs/review.md** | Review criteria summary. | CLI init / manual copy |
+| **docs/rules-by-platform.md** | Per-platform rules summary. | CLI init / manual copy |
+| **.gitignore** (block) | Common + **chosen platform** ignore patterns. | CLI init (varies by platform) |
+
+With the CLI, choosing a **platform** sets `platform` in `ai.config.yml` and appends that platform’s patterns to `.gitignore`.
+
+---
+
+## 2. ai.config.yml — What each section controls
+
+| Section | What it adds/controls | When changing later |
+|---------|------------------------|----------------------|
+| **model** | Default model and option list. | Edit `model.default`, `model.options`. Add `task_presets.<name>.model` for per-preset model. |
+| **context** | Which paths to include/exclude, max_files, max_tokens. | Adjust `include`/`exclude` to your project layout. |
+| **system_role** | File that defines the system role (quality, security, errors, etc.). | Usually keep. To change, edit the `prompt` in the YAML it points to. |
+| **prompts** | Named prompt files (default, review, etc.). | Add names or change paths. |
+| **task_presets** | Per-task prompt, extra rules, model. | Add presets or edit `prompt`/`rules_extra`/`model`. |
+| **platform** | Current platform (ios \| android \| flutter \| web \| server). null = no platform merge. | Set e.g. `platform: ios` to apply that platform’s config. |
+| **platforms** | Per-platform context.include and rules_key. | Adjust `platforms.<id>.context.include` to your paths. |
+| **rules** | Global rules (no_auto_scan, strict, cite_sources, etc.). | Toggle here if your tool supports them. |
+
+---
+
+## 3. Prompt files — What each adds
+
+| File | Rules it adds (summary) | When applied |
+|------|-------------------------|--------------|
+| **prompts/system.core.yml** | Role, response, code quality, security, errors, docs, collaboration. MUST/MUST NOT. | Used by `system_role`, `prompts.default`, most task presets. |
+| **prompts/review.yml** | Review scope, checklist (consistency, quality, security, errors, compatibility), output format, approve/request-changes. | Used by `prompts.review`, presets `review`, `security_audit`. |
+| **prompts/rules.by-platform.yml** | Per-platform rules (iOS, Android, Flutter, Web, Server, common). | When `platform` is set, the matching `platforms.<id>.prompt` is merged after the system role. |
+| **prompts/guide.template.yml** | Task template fields (platform, role, context, task, constraints, output). | For humans to copy and fill; not auto-injected by tools. |
+
+---
+
+## 4. Task presets — What each adds when selected
+
+| Preset | Prompt used | Extra rules (rules_extra) |
+|--------|--------------|---------------------------|
+| **default** | system.core.yml | None |
+| **review** | review.yml | None |
+| **refactor** | system.core.yml | No behavior change, preserve semantics; small, single logical change per step. |
+| **implement** | system.core.yml | Implement only what’s specified; add tests or test plan. |
+| **fix_bug** | system.core.yml | Find root cause; minimal fix; no unnecessary refactor. |
+| **security_audit** | review.yml | Focus on secrets, input validation, auth boundaries, sensitive data in logs. |
+
+Changing the preset applies **different rules/prompts for that task only** in the same project.
+
+---
+
+## 5. Platforms — What gets merged when selected
+
+| Platform | Example context.include | Rules (from) |
+|----------|-------------------------|--------------|
+| **ios** | ios/**, *.xcodeproj/**, Shared/**, src/** | rules.by-platform → platforms.ios.prompt |
+| **android** | android/**, app/**, lib/**, src/** | platforms.android.prompt |
+| **flutter** | lib/**, ios/**, android/**, test/**, pubspec.yaml | platforms.flutter.prompt |
+| **web** | src/**, public/**, app/**, *.config.js, etc. | platforms.web.prompt |
+| **server** | src/**, lib/**, app/**, internal/**, cmd/** | platforms.server.prompt |
+
+If `platform: null`, no platform merge is applied and only the top-level **context** in `ai.config.yml` is used.
+
+---
+
+## 6. Later changes — What to edit by scenario
+
+| Goal | What to change |
+|------|----------------|
+| **Switch platform** | Change `platform` in `ai.config.yml`. Optionally adjust `platforms.<id>.context.include` for your paths. |
+| **Stricter review** | Use `task_presets.review` (already wired). To tighten, edit `prompt` in `prompts/review.yml`. |
+| **Adjust context scope** | Edit `context.include`/`context.exclude` for your layout; if using a platform, also `platforms.<id>.context.include`. |
+| **Change model only** | Change `model.default`. Add `task_presets.<name>.model` for a specific task. |
+| **Add a task preset** | Add a new entry under `task_presets` with `description`, `prompt`, and optionally `rules_extra`, `model`. |
+| **Project-specific rules** | Add to `prompt` in `prompts/system.core.yml` or add a new YAML and reference it from `system_role`/`prompts`. |
+
+---
+
+## 7. Using this in any project
+
+- **Install**: Run `prompt-guide init` (or copy `ai/`, `prompts/`, `docs/` manually). Then run `prompt-guide doctor`; if only .gitignore is missing, run `prompt-guide doctor --fix`.
+- **Common layout**: `ai.config.yml` + `prompts/system.core.yml` + `prompts/review.yml` + `prompts/rules.by-platform.yml` is the same **for all languages and frameworks**.
+- **Project-specific**: Only `context.include`/`exclude`, `platform`, `platforms.<id>.context.include`, and optionally `model.default` and presets.
+- **Docs**: Rule summaries are in `docs/system.core.md`, `docs/review.md`, `docs/rules-by-platform.md`. CLI usage in `docs/CLI.md`. YAML is for tools; Markdown is for humans.
+
+This document is a single place to see **what each part adds** and **what to change later** after install.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "prompt-guide-cli",
+  "version": "1.0.0",
+  "description": "Initialize prompt-guide in any project: pick platform, copy config, set .gitignore",
+  "type": "module",
+  "bin": {
+    "prompt-guide": "./bin/cli.js"
+  },
+  "keywords": [
+    "prompt-guide",
+    "cursor",
+    "ai",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "ai",
+    "docs",
+    "prompts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "copy-templates": "node scripts/copy-templates.cjs",
+    "prepublishOnly": "npm run copy-templates && npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "figlet": "^1.10.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/prompts/guide.template.yml

@@ -0,0 +1,32 @@
+# Task prompt template (assumes system.core + platform rules apply)
+# Copy, fill values, then paste into the AI. Use as YAML or render from the prompt_example below.
+
+meta:
+  name: guide.template
+  platform_agnostic: true
+
+# Fields to fill (remove comments and enter values)
+fields:
+  platform: "iOS | Android | Flutter | Web | Server | Other"
+  role: "One-line role, e.g. Modify the iOS app in this repo"
+  context:
+    project: ""
+    path: ""
+    stack: ""
+    rules_ref: "e.g. rules.by-platform block for this platform"
+  task: "Clear verb: what to implement/fix/verify"
+  constraints: []
+  output:
+    format: "code only | explanation+code | checklist etc."
+    include: "usage, how to test, caveats etc."
+  example: ""
+
+# Render example (combine in this format after filling fields)
+prompt_example: |
+  Platform: {{ platform }}
+  Role: {{ role }}
+  Context: project {{ context.project }}, path {{ context.path }}, stack {{ context.stack }}. Rules: {{ context.rules_ref }}
+  Task: {{ task }}
+  Constraints: {{ constraints }}
+  Output: format {{ output.format }}, include {{ output.include }}
+  Example: {{ example }}

package/prompts/review.yml

@@ -0,0 +1,28 @@
+# Code Review — same strict criteria, assumes system.core
+# Tools: use this file's prompt key. Human-readable: docs/review.md
+
+meta:
+  name: review
+  strict: true
+  platform_agnostic: true
+
+prompt: |
+  # Review (required criteria, platform agnostic)
+
+  ## Scope (required review targets)
+  MUST: Review all of — full diff, new dependencies, config and env changes.
+
+  ## Checklist (per item: report only violations as file:line and concrete description; omit passing items)
+  1. Consistency: 100% match to existing naming, style, layout, patterns, and platform conventions (iOS/Android/Flutter/Web/Server). Call out any mismatch.
+  2. Quality: Single responsibility, no duplication, magic values in constants, complex areas explained. Request changes if not met.
+  3. Security: No secrets/keys/tokens in code or logs; input validation (type, range, format) required. Request changes on violation.
+  4. Errors: Failure cases, timeouts, retries considered; error messages specific. Call out if missing.
+  5. Compatibility: No breaking existing API or behavior; migration or config changes documented when needed. Request changes if broken or undocumented.
+
+  ## Output format (required)
+  MUST: Summary in 1–2 sentences (Approve / Conditional approve / Request changes).
+  MUST: Only violated items, in the order above, as file:line and concrete description.
+  MUST: If you have a fix to suggest, give a code snippet or steps.
+  SHOULD: One or two lines on what’s good.
+
+  If any item is not satisfied, conclude "Request changes". Only conclude "Approve" when all items pass.

package/prompts/rules.by-platform.yml

@@ -0,0 +1,59 @@
+# Per-platform rules (when forking, use only the relevant platform(s); merge if multiple)
+# Tools: use platforms.<name>.prompt. Human-readable: docs/rules-by-platform.md
+
+meta:
+  strict: true
+  usage: "system.core + selected platform prompt merged"
+
+platforms:
+  ios:
+    name: iOS
+    stack: Swift / SwiftUI / UIKit
+    prompt: |
+      ## iOS (required additional rules)
+      MUST: Follow project style for Swift naming, indentation, optionals, and error handling. Keep Podfile, SPM, or Carthage lock; do not change versions arbitrarily.
+      MUST: Consider UI accessibility (VoiceOver, Dynamic Type), dark mode, and localization. UI updates on main thread only.
+      MUST NOT: Store secrets in code or plist. Use Keychain or env only. No PII or tokens in logs.
+
+  android:
+    name: Android
+    stack: Kotlin / Java
+    prompt: |
+      ## Android (required additional rules)
+      MUST: Follow Kotlin/Java conventions and package layout. Keep Gradle and version catalog in sync; do not change versions arbitrarily.
+      MUST: Consider a11y (contentDescription, TalkBack), settings, localization, themes. UI work on Main dispatcher only.
+      MUST NOT: Store secrets in code or resources. Use Keystore, BuildConfig, or env. No PII in logs or crash reports.
+
+  flutter:
+    name: Flutter
+    stack: Dart
+    prompt: |
+      ## Flutter (required additional rules)
+      MUST: Follow effective_dart and project analysis options. Keep pubspec.lock and version ranges; do not change arbitrarily.
+      MUST: Consider accessibility (Semantics, labels), responsive layout, localization. Use async/await and Future for async; keep build synchronous.
+      MUST NOT: Store secrets in code. Use flutter_dotenv, --dart-define, or native secrets. No secrets or PII in logs.
+
+  web:
+    name: Web
+    stack: JS/TS · React/Vue/Svelte etc.
+    prompt: |
+      ## Web (required additional rules)
+      MUST: Follow project framework, bundler, and lint rules. Keep package-lock, yarn.lock, or pnpm-lock; do not change arbitrarily.
+      MUST: Consider a11y (semantics, ARIA, keyboard, focus), responsive layout, i18n. Keep CSR/SSR and hydration consistent.
+      MUST NOT: Ship secrets in client code or build output. Use env or build-time injection. Consider XSS, CORS, CSP. No PII in logs or errors.
+
+  server:
+    name: Server
+    stack: Node/Go/Rust/Java/Python etc.
+    prompt: |
+      ## Server (required additional rules)
+      MUST: Follow project conventions and directory layout. Keep lockfile, go.sum, Cargo.lock, requirements.txt, etc.; do not change arbitrarily.
+      MUST: Use a consistent API response shape (e.g. { success, data?, error? }). Apply HTTP 2xx/4xx/5xx, timeouts, rate limits. Long work in queue/background only.
+      MUST NOT: Store secrets in code. Use env or a secret manager. Do not skip input validation, auth, or authorization. No secrets or PII in logs.
+
+  common:
+    name: Common
+    prompt: |
+      ## Common (all platforms, required)
+      MUST: Add unit tests for public API and utilities. Test names: "condition → expected". Mock only external dependencies.
+      MUST: Commits: "verb + object". One commit = one logical change. PRs must state reason, how to test, and whether there are breaking changes.

package/prompts/system.core.yml

@@ -0,0 +1,49 @@
+# System Core — base rules for all prompts (enforced)
+# Tools: use this file's prompt key. Human-readable: docs/system.core.md
+
+meta:
+  name: system.core
+  strict: true
+  platform_agnostic: true
+  scope: all
+
+prompt: |
+  # System Core (required rules; request changes if not met)
+
+  ## Scope
+  MUST: Apply identically to all platform forks (iOS, Android, Flutter, Web, Server). Language and framework neutral.
+
+  ## Role and response (required)
+  MUST: Understand the request, reflect context, and only provide actionable results.
+  MUST: For ambiguous requirements, pick one reasonable interpretation, state it, then proceed.
+  MUST: Structure responses (steps, code blocks, file:line references). When suggesting alternatives, give recommendation and reason in one line.
+
+  ## Code quality (required)
+  MUST: Naming must reveal intent. No magic numbers or strings — use constants or config.
+  MUST: Keep existing indentation, quotes, naming, and directory structure 100%. New code must follow existing patterns.
+  MUST: Functions and classes have single responsibility. Split by logical unit when violated.
+  MUST: No repeated logic — extract to functions, utils, or shared components.
+  MUST: Minimize dependencies. Respect the platform lockfile (Podfile, Gradle, pubspec, package.json, Cargo.toml, etc.). Do not change versions arbitrarily.
+
+  ## Security (required; request changes on violation)
+  MUST NOT: Put secrets, keys, or tokens in code, commits, or comments. Use env or a secret manager only.
+  MUST: Validate user and external input (type, length, range, format, allow-list) before use. Do not skip validation.
+  MUST NOT: Include secrets or PII in logs, errors, or responses.
+
+  ## Errors and robustness (required)
+  MUST: Always consider failure cases: network, files, API, bad input, timeouts.
+  MUST: Error messages must be specific enough to debug; include stack/code location when possible.
+  MUST: If retry, fallback, or partial success is possible, state and implement it.
+
+  ## Documentation and maintenance (required)
+  MUST: Comments explain "why" only; "what" from names and structure. Comment complex algorithms and business rules.
+  MUST: Document public APIs (purpose, arguments, return value, exceptions; e.g. docstrings, OpenAPI).
+  MUST: Do not make breaking or behavior changes without checking call sites and compatibility.
+
+  ## Collaboration and checks (required)
+  MUST: Respond in the user's chosen language. Follow project conventions for code and variable names.
+  MUST: When referring to code, give path and line.
+  MUST: Before submitting — style match, error handling, no secrets, tests/validation, existing behavior preserved. If any is missing, fix before submitting.
+
+  ## Exceptions
+  Only relax or skip a rule when the user explicitly says so (e.g. "ignore style for this edit"). Without that, all rules above apply.