Harden prompt-doc example link hygiene and codify placeholder-path policy

.markdownlint-cli2.jsonc

@@ -0,0 +1,16 @@
+{
+  "config": {
+    "MD010": {
+      "code_blocks": false
+    },
+    "MD013": false,
+    "MD022": false,
+    "MD024": false,
+    "MD031": false,
+    "MD032": false,
+    "MD033": false,
+    "MD040": false,
+    "MD058": false,
+    "MD060": false
+  }
+}

CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+- **LLM-friendly repository index** — Added root `llms.txt` with concise start points, core prompt, governance files, key specialist prompts, and archive index
+- **Prompt archive index** — Added `prompts/english/agents/archive/INDEX.md` with keep/merge/archive classification and rationale
+- **Portfolio Maintenance Guide** — Added `prompts/english/workflows/portfolio-maintenance-guide.md` with monthly + quarterly governance cadence
+- **Compatibility stubs for archived prompts** — Added deprecation redirect files for archived prompt paths
+- **Repository markdownlint baseline config** — Added `.markdownlint-cli2.jsonc` aligned with current repository Markdown conventions to reduce noisy lint failures on dense prompt docs
+
+### Changed
+- **Primary documentation navigation** — Added `llms.txt` links in README and QUICK-START for faster agent/document discovery
+- **Internal example link hygiene** — Replaced non-existent markdown links in prompt examples with explicit example-path code literals to avoid broken internal references
+- **Contribution guidance for example paths** — Added a checklist rule in `CONTRIBUTING.md` to keep hypothetical paths as code literals instead of Markdown links
+- **Contribution checklist** — Added `llms.txt` maintenance check when core navigation or prompt structure changes
+- **Outcome-first repository structure** — Reworked README, QUICK-START, USAGE, and prompt indexes around “Agent System first + one specialist” selection
+- **Agent catalog model** — Split active catalog from archived prompts and removed archived prompts from active listings
+- **Contribution quality gates** — Added no-vague-advice rule and archive workflow to CONTRIBUTING and CLAUDE guidance
+- **Core docs code fences** — Added explicit `text` language tags to unlabeled fenced blocks in README and QUICK-START
+- **Lint compatibility tuning** — Adjusted markdownlint baseline for intentional prompt-document patterns (collapsible HTML sections and Makefile tabs in code blocks)
+- **Prompt formatting cleanup** — Fixed heading style issues in `general-software-development-prompt.md` (`Arrange-Act-Assert` heading and `C#` heading rendering)
+
+### Removed
+- **Five prompts from active catalog** — Error Analysis, Project Workflow, Integration Guardian, Claude Code Token Optimization, and Prompt Chaining moved to archive
+
 ### Added
 - **Database Design & Optimization prompt** — QUERY protocol for schema design, normalization decisions, composite indexing strategy, EXPLAIN ANALYZE workflow, N+1 detection, connection pooling, zero-downtime migration patterns, and performance monitoring queries
 - **UI/UX & Design Systems prompt** — DESIGN protocol for design token hierarchy (global → alias → component), variant-driven components (CVA), compound component pattern, accessibility by default (WCAG 2.2), responsive patterns, Storybook documentation, theme system with dark mode, and visual regression testing

CLAUDE.md

@@ -20,12 +20,13 @@
 └── prompts/
     └── english/
         ├── INDEX.md           # All prompts organized by category
-        ├── agents/            # Agent-optimized prompts (34 files)
-        │   └── INDEX.md
+        ├── agents/            # Active agent prompts + compatibility stubs
+        │   ├── INDEX.md
+        │   └── archive/       # Archived prompts removed from active catalog
         ├── base/              # Foundation prompt (universal best practices)
         ├── project-types/     # Domain-specific prompts (11 files: web, API, ML, mobile, blockchain, desktop, etc.)
         ├── examples/          # Real-world usage examples (10 files)
-        └── workflows/         # APEI methodology, prompt selection, troubleshooting, setup & best practices guides
+        └── workflows/         # APEI methodology, prompt selection, troubleshooting, setup, and maintenance guides
 ```
 
 ## File Naming Conventions
@@ -108,6 +109,12 @@ No build system — this is a pure Markdown repository.
 2. Ensure all relative links still resolve
 3. Keep `CHANGELOG.md` updated for notable changes
 
+### Archive overlapping prompts
+1. Classify prompt as keep / merge / archive
+2. Move archived prompt to `prompts/english/agents/archive/`
+3. Add archive rationale in `prompts/english/agents/archive/INDEX.md`
+4. Update active catalogs (`README.md`, `prompts/english/agents/INDEX.md`, `prompts/english/INDEX.md`)
+
 ## Quality Checklist
 
 Before submitting changes:
@@ -119,6 +126,7 @@ Before submitting changes:
 - [ ] Follows existing naming conventions (`kebab-case-prompt.md`)
 - [ ] New prompts include Role, Protocol, Phases, and Remember sections
 - [ ] README.md catalog tables updated if adding new prompts
+- [ ] Recommendations are concrete (no vague advice)
 
 ## Commit Messages
 

CONTRIBUTING.md

@@ -1,92 +1,63 @@
 # Contributing
 
+## Scope
+
+This repository is **English-only** and **Markdown-only**.
+
 ## How to Contribute
 
 | Type | Description |
 |------|-------------|
-| **New Project Types** | Desktop apps, data engineering, etc. |
-| **New Agent Types** | Specialized agent prompts with protocol acronyms |
-| **New Examples** | Real-world walkthroughs demonstrating APEI cycle |
-| **Improvements** | Better practices, clearer instructions, examples |
-| **Bug Fixes** | Typos, broken links, formatting issues |
-
-## Quick Setup
-
-```bash
-git clone https://github.com/Rtur2003/Claude-Code-Promts.git
-cd Claude-Code-Promts
-git checkout -b feature/your-feature-name
-```
-
-## File Structure
-
-```
-prompts/
-└── english/
-    ├── agents/           # Agent-optimized prompts (34 files)
-    ├── base/             # Foundation prompts
-    ├── project-types/    # Domain-specific prompts (11 files)
-    ├── examples/         # Usage examples (10 files)
-    └── workflows/        # Process guides (5 files)
-```
+| New prompts | Agent, project-type, or workflow prompts |
+| Improvements | Better structure, clarity, outcome quality |
+| Examples | Real-world APEI walkthroughs |
+| Maintenance | Link fixes, catalog cleanup, archive actions |
 
-## Naming Convention
+## Prompt Quality Standard
 
-| Type | Format | Example |
-|------|--------|---------|
-| Prompts | `kebab-case-prompt.md` | `code-review-prompt.md` |
-| Guides | `kebab-case-guide.md` | `iterative-development-guide.md` |
-| Index | `INDEX.md` | `INDEX.md` |
+Every prompt must contain:
+- `## Role`
+- `## Protocol / Core Loop`
+- `## Phases`
+- `## Remember` (final section)
 
-## Prompt Template
+### No Vague Advice Rule
 
-```markdown
-# Prompt Title
+Every recommendation should end with a concrete:
+- decision, or
+- tool, or
+- validation step.
 
-> **Key Feature 1** | **Key Feature 2** | **Key Feature 3**
+## Archive Workflow
 
-## Role
-[Define what this prompt does]
+If a prompt is low-value or overlapping:
+1. Classify as keep / merge / archive
+2. Move to `prompts/english/agents/archive/`
+3. Update active indexes and README
+4. Add rationale to archive index
 
-## Protocol / Core Loop
-[Main workflow]
+## Validation Before PR
 
-## Phases
-[Phase details with templates and checklists]
-
-## Remember
-[Key takeaways]
-```
-
-## Checklist Before Submitting
-
-- [ ] Content is accurate and follows best practices
 - [ ] Markdown renders correctly
 - [ ] No spelling or grammar errors
-- [ ] INDEX files updated
-- [ ] Links work correctly
-- [ ] Follows existing style
+- [ ] Internal relative links resolve
+- [ ] Hypothetical example paths are plain code literals (not Markdown links)
+- [ ] Catalog/index entries are updated
+- [ ] `llms.txt` is updated when primary navigation or core prompts change
+- [ ] No vague advice language
 
-## Commit Messages
+Optional local checks:
 
 ```bash
-feat: add security audit prompt       # New features
-fix: correct typo in API prompt        # Fixes
-docs: improve README examples          # Documentation
-update: enhance code review checklist  # Updates
+grep -r '\[.*\](.*\.md)' prompts/ | head
+npx markdownlint-cli2 '**/*.md'
 ```
 
-## Pull Request Process
-
-1. Create branch → make changes → commit
-2. Push and create PR with clear description
-3. Address review feedback
-4. Merge after approval
+## Commit Message Style
 
-## License
-
-Contributions are licensed under MIT License.
-
----
-
-Thank you for contributing! 🚀
+```text
+feat: add new prompt
+fix: correct catalog link
+docs: improve usage guidance
+update: archive overlapping prompt
+```

QUICK-START.md

@@ -1,116 +1,44 @@
 # Quick Start
 
-## 1. Pick Your Prompt
+## 1) Start Minimal
 
-### AI Agents (Claude Code, Copilot, etc.)
+| Situation | Prompt Setup |
+|-----------|--------------|
+| Any autonomous coding task | **Agent System** ⭐ |
+| Tight token budget | **Quick Reference** |
+| Claude Code setup | Agent System + **Claude Code Workflow** |
+| Production debugging | Agent System + **Debugging & Troubleshooting** |
+| Security-sensitive task | Agent System + **Security Audit** |
 
-| Task | Prompt | File |
-|------|--------|------|
-| Any autonomous task | **Agent System** ⭐ | [View](prompts/english/agents/claude-agent-system-prompt.md) |
-| Debugging | Agent System + **Error Analysis** | [View](prompts/english/agents/error-analysis-prompt.md) |
-| New/existing project | Agent System + **Project Workflow** | [View](prompts/english/agents/project-workflow-prompt.md) |
-| PR review | Agent System + **Code Review** | [View](prompts/english/agents/code-review-prompt.md) |
-| Security check | Agent System + **Security Audit** | [View](prompts/english/agents/security-audit-prompt.md) |
-| Code improvement | Agent System + **Refactoring** | [View](prompts/english/agents/refactoring-prompt.md) |
-| Test design | Agent System + **Testing** | [View](prompts/english/agents/testing-strategies-prompt.md) |
-| Technical writing | Agent System + **Documentation** | [View](prompts/english/agents/documentation-prompt.md) |
-| Optimize performance | Agent System + **Performance** | [View](prompts/english/agents/performance-optimization-prompt.md) |
-| Git workflow | Agent System + **Git & VCS** | [View](prompts/english/agents/git-version-control-prompt.md) |
-| System integrity | Agent System + **Integration Guardian** | [View](prompts/english/agents/integration-guardian-prompt.md) |
-| Accessibility check | Agent System + **Accessibility Audit** | [View](prompts/english/agents/accessibility-audit-prompt.md) |
-| Migration/upgrade | Agent System + **Migration & Upgrade** | [View](prompts/english/agents/migration-upgrade-prompt.md) |
-| Set up monitoring | Agent System + **Monitoring & Observability** | [View](prompts/english/agents/monitoring-observability-prompt.md) |
-| Production debugging | Agent System + **Debugging & Troubleshooting** | [View](prompts/english/agents/debugging-troubleshooting-prompt.md) |
-| Minimal context | **Quick Reference** only | [View](prompts/english/agents/agent-quick-reference.md) |
+## 2) Add One Specialist Only If Needed
 
-### Claude Code-Specific
+Need criteria: add a specialist only when Agent System alone cannot provide domain-specific protocols for your task.
 
-| Task | Prompt | File |
-|------|--------|------|
-| Mode planning (/think, /ultrathink) | **Claude Code Modes** ⭐ | [View](prompts/english/agents/claude-code-modes-prompt.md) |
-| Token efficiency | **Claude Code Tokens** | [View](prompts/english/agents/claude-code-token-optimization-prompt.md) |
-| CLAUDE.md & hooks setup | **Claude Code Workflow** | [View](prompts/english/agents/claude-code-workflow-prompt.md) |
+| Need | Add |
+|------|-----|
+| Architecture decisions | Architecture Patterns |
+| Tool/library selection | Technology Stack |
+| Multi-agent parallel flow | Multi-Agent Orchestration |
+| Performance bottlenecks | Performance Optimization |
+| Reliability hardening | Error Handling & Resilience |
 
-### Architecture & Development
+## 3) Use APEI Loop
 
-| Task | Prompt | File |
-|------|--------|------|
-| Tool/library selection | **Technology Stack** ⭐ | [View](prompts/english/agents/technology-stack-prompt.md) |
-| System design & patterns | **Architecture Patterns** | [View](prompts/english/agents/architecture-patterns-prompt.md) |
-| Modern full-stack app | **Full-Stack Development** | [View](prompts/english/agents/fullstack-development-prompt.md) |
-| Complex multi-step tasks | **Prompt Chaining** | [View](prompts/english/agents/prompt-chaining-prompt.md) |
-| Add AI/LLM features | **AI & LLM Integration** | [View](prompts/english/agents/ai-llm-integration-prompt.md) |
-| API design / GraphQL | **API Design & GraphQL** | [View](prompts/english/agents/api-design-graphql-prompt.md) |
-| Cloud deployment | **Cloud & Infrastructure** | [View](prompts/english/agents/cloud-infrastructure-prompt.md) |
-| Data pipelines | **Data Engineering** | [View](prompts/english/agents/data-engineering-prompt.md) |
-| Compliance audit | **Compliance & Governance** | [View](prompts/english/agents/compliance-governance-prompt.md) |
-| Multi-agent coordination | **Multi-Agent Orchestration** | [View](prompts/english/agents/multi-agent-orchestration-prompt.md) |
-| Monorepo / complex project | **Monorepo & Complex Projects** | [View](prompts/english/agents/monorepo-complex-projects-prompt.md) |
-| Error handling / resilience | **Error Handling & Resilience** | [View](prompts/english/agents/error-handling-resilience-prompt.md) |
-| Developer experience / tooling | **Developer Experience & Tooling** | [View](prompts/english/agents/developer-experience-tooling-prompt.md) |
-| Database design / optimization | **Database Design & Optimization** | [View](prompts/english/agents/database-optimization-prompt.md) |
-| UI components / design system | **UI/UX & Design Systems** | [View](prompts/english/agents/ui-design-systems-prompt.md) |
-
-### Interactive Sessions
-
-| Project | Prompts | Files |
-|---------|---------|-------|
-| Any project | **Foundation** ⭐ | [View](prompts/english/base/claude-foundation-prompt.md) |
-| React / Vue app | Foundation + **Web Dev** | [View](prompts/english/project-types/web-development-prompt.md) |
-| REST / GraphQL API | Foundation + **API Dev** | [View](prompts/english/project-types/api-development-prompt.md) |
-| ML / Data Science | Foundation + **Data Science** | [View](prompts/english/project-types/data-science-ml-prompt.md) |
-| iOS / Android app | Foundation + **Mobile** | [View](prompts/english/project-types/mobile-development-prompt.md) |
-| DevOps / Infra | Foundation + **DevOps** | [View](prompts/english/project-types/devops-cicd-prompt.md) |
-| Database design | Foundation + **Database** | [View](prompts/english/project-types/database-sql-prompt.md) |
-| General software | Foundation + **General Software** | [View](prompts/english/project-types/general-software-development-prompt.md) |
-| Game development | Foundation + **Game Dev** | [View](prompts/english/project-types/game-development-prompt.md) |
-| Embedded / IoT | Foundation + **Embedded & IoT** | [View](prompts/english/project-types/embedded-iot-prompt.md) |
-| Smart contracts | Foundation + **Blockchain & Web3** | [View](prompts/english/project-types/blockchain-web3-prompt.md) |
-| Desktop app | Foundation + **Desktop Apps** | [View](prompts/english/project-types/desktop-development-prompt.md) |
-| Full-stack app | Foundation + Web + API | — |
-
----
-
-## 2. Copy & Paste
-
-**Agent mode:** Copy the prompt file content → paste as system prompt → give your task.
-
-**Interactive mode:** Copy Foundation + project prompt → paste at session start → describe your task.
-
----
-
-## 3. Core Method (APEI)
-
-```
+```text
 ANALYZE → PLAN → EXECUTE → ITERATE
-   ↑                          │
-   └── Not optimal? ──────────┘
 ```
 
-All prompts follow this cycle automatically.
-
----
-
-## Token Budget
+## 4) Token Budget
 
 | Budget | Setup |
 |--------|-------|
 | < 2K | Quick Reference only |
-| 2K–8K | Agent System Prompt |
-| 8K+ | Agent System + project-type prompt |
-
----
+| 2K–8K | Agent System |
+| 8K+ | Agent System + 1 specialist |
 
-## Documentation
+## 5) Catalogs
 
-- [README.md](README.md) — Full catalog & overview
-- [USAGE.md](USAGE.md) — Detailed examples
-- [CHANGELOG.md](CHANGELOG.md) — Version history
-- [CLAUDE.md](CLAUDE.md) — AI agent configuration for this repo
-- [Agent Index](prompts/english/agents/INDEX.md) — All agent prompts
-- [Prompt Index](prompts/english/INDEX.md) — All prompts by category
-- [Prompt Selector](prompts/english/workflows/prompt-selector-guide.md) — Decision tree for choosing prompts
-- [Workflow Guide](prompts/english/workflows/iterative-development-guide.md) — APEI deep-dive
-- [Troubleshooting Guide](prompts/english/workflows/troubleshooting-guide.md) — Issue diagnosis flowchart
-- [Claude Code Setup Guide](prompts/english/workflows/claude-code-setup-guide.md) — `.claude/` directory, CLAUDE.md hierarchy, prompt placement
-- [Best Practices Guide](prompts/english/workflows/best-practices-customization-guide.md) — Prompt customization & team standards
+- [Active Agent Index](prompts/english/agents/INDEX.md)
+- [Archived Prompt Index](prompts/english/agents/archive/INDEX.md)
+- [Global Prompt Index](prompts/english/INDEX.md)
+- [LLM Index](llms.txt)