Skip to content

Commit bae661e

Browse files
AybarsBarutAybarsBarut
committed
Add repository maturity workflow
1 parent 475b1b5 commit bae661e

25 files changed

Lines changed: 846 additions & 2 deletions

‎.github/CODEOWNERS‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Nexus-APCP ownership map.
2+
# Replace @AybarsBarut with a team handle when the project gains maintainers.
3+
4+
* @AybarsBarut
5+
6+
# Public positioning and repository metadata
7+
README.md @AybarsBarut
8+
docs/SEO_CHECKLIST.md @AybarsBarut
9+
codemeta.json @AybarsBarut
10+
CITATION.cff @AybarsBarut
11+
.github/repository-metadata.yml @AybarsBarut
12+
13+
# Protocol and prompt surface
14+
AI_PROJECT_CONTEXT_PROTOCOL.md @AybarsBarut
15+
AI_MAIN.md @AybarsBarut
16+
AI_ASSISTANT_PROMPT_TEMPLATES.md @AybarsBarut
17+
MASTER_PROMPT.md @AybarsBarut
18+
CAVEMAN_RULES.md @AybarsBarut
19+
DECISION_LOG_PROTOCOL.md @AybarsBarut
20+
21+
# Safety-sensitive docs
22+
SECURITY.md @AybarsBarut
23+
DOMAIN_SPECIFIC_GITIGNORE_PROTOCOLS.md @AybarsBarut
24+
WORKSPACE_SPECIFIC_DELIVERY_PROTOCOLS.md @AybarsBarut
25+
26+
# Automation and validation
27+
scripts/ @AybarsBarut
28+
.github/workflows/ @AybarsBarut

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Bug report
2+
description: Report a broken command, bad link, incorrect instruction, or repository behavior problem.
3+
title: "fix: "
4+
labels:
5+
- bug
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for helping improve Nexus-APCP. Do not include secrets, private project context, generated private prompt bundles, or exploit details.
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: Problem
15+
description: What is broken or incorrect?
16+
placeholder: The setup guide references a file that does not exist.
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: steps
21+
attributes:
22+
label: Steps to reproduce
23+
description: List the exact command, file, or section involved.
24+
placeholder: |
25+
1. Open ...
26+
2. Run ...
27+
3. See ...
28+
- type: textarea
29+
id: expected
30+
attributes:
31+
label: Expected behavior
32+
description: What should happen instead?
33+
- type: dropdown
34+
id: area
35+
attributes:
36+
label: Area
37+
options:
38+
- README
39+
- Protocol template
40+
- Prompt templates
41+
- Scripts
42+
- GitHub metadata
43+
- Examples
44+
- Security guidance
45+
- Other
46+
validations:
47+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Security-sensitive report
4+
url: https://github.com/AybarsBarut/Nexus-APCP/security/advisories/new
5+
about: Use private vulnerability reporting when available. Do not disclose sensitive details in public issues.
6+
- name: Repository SEO checklist
7+
url: https://github.com/AybarsBarut/Nexus-APCP/blob/master/docs/SEO_CHECKLIST.md
8+
about: Check current repository positioning, topics, and metadata before opening SEO-related issues.

‎.github/ISSUE_TEMPLATE/docs_improvement.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Documentation improvement
2+
description: Suggest clearer wording, missing setup steps, or better examples.
3+
title: "docs: "
4+
labels:
5+
- documentation
6+
body:
7+
- type: textarea
8+
id: section
9+
attributes:
10+
label: Documentation section
11+
description: Which file or section should change?
12+
placeholder: README.md Quick Start, SETUP_GUIDE.md Step 2, etc.
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: improvement
17+
attributes:
18+
label: Suggested improvement
19+
description: Explain what is confusing or missing.
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: audience
24+
attributes:
25+
label: Intended audience
26+
description: Who benefits from this change?
27+
placeholder: New users, maintainers, AI agents, teams adopting Cursor, etc.

‎.github/ISSUE_TEMPLATE/protocol_suggestion.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Protocol suggestion
2+
description: Propose a new Nexus-APCP workflow, prompt, delivery gate, or example kit.
3+
title: "feat: "
4+
labels:
5+
- enhancement
6+
body:
7+
- type: textarea
8+
id: use_case
9+
attributes:
10+
label: Use case
11+
description: What AI-assisted development scenario should Nexus-APCP support better?
12+
validations:
13+
required: true
14+
- type: textarea
15+
id: proposal
16+
attributes:
17+
label: Proposal
18+
description: Describe the protocol, template, checklist, or example you want added.
19+
validations:
20+
required: true
21+
- type: textarea
22+
id: safety
23+
attributes:
24+
label: Safety and privacy considerations
25+
description: Note any private context, secrets, customer data, or security risks this workflow must avoid.
26+
- type: dropdown
27+
id: domain
28+
attributes:
29+
label: Domain
30+
options:
31+
- General AI-assisted development
32+
- Web app
33+
- Backend/API
34+
- AI/RAG/LLM
35+
- Mobile
36+
- Game development
37+
- DevOps/Infrastructure
38+
- Security/Penetration testing
39+
- Other
40+
validations:
41+
required: true

‎.github/ISSUE_TEMPLATE/security_private.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Security-sensitive issue
2+
description: Use this only for non-sensitive security process improvements. Do not disclose vulnerabilities publicly.
3+
title: "security: "
4+
labels:
5+
- security
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
If this is a vulnerability report, do not continue here. Use GitHub private vulnerability reporting if available, or request a private contact without sharing details.
11+
- type: textarea
12+
id: safe_summary
13+
attributes:
14+
label: Safe summary
15+
description: Describe the documentation or process improvement without exploit details.
16+
validations:
17+
required: true
18+
- type: checkboxes
19+
id: confirmation
20+
attributes:
21+
label: Public safety confirmation
22+
options:
23+
- label: This issue does not include secrets, exploit details, private infrastructure, customer data, or generated private context.
24+
required: true

‎.github/pull_request_template.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## Summary
2+
3+
Describe what changed and why it matters for Nexus-APCP users.
4+
5+
## Change Type
6+
7+
- [ ] Protocol or template change
8+
- [ ] Documentation improvement
9+
- [ ] Prompt/template improvement
10+
- [ ] Repository metadata or SEO
11+
- [ ] Script or validation change
12+
- [ ] Security or safe-publishing guidance
13+
- [ ] Example kit update
14+
15+
## Review Checklist
16+
17+
- [ ] The change is sanitized for public release.
18+
- [ ] README, SEO metadata, and related docs stay consistent when public positioning changed.
19+
- [ ] File links and command examples are valid.
20+
- [ ] Private context, secrets, generated prompt bundles, and sensitive security details are not included.
21+
- [ ] `python scripts/validate-repo.py` passes, or the reason it was skipped is explained.
22+
- [ ] `TASK_PROGRESS.yaml` is updated when this completes a tracked repository task.
23+
24+
## Notes for Reviewers
25+
26+
Mention any tradeoffs, follow-up work, or areas that need extra attention.

‎.github/pull_request_title_conventions.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Pull Request Title Conventions
2+
3+
Nexus-APCP uses simple conventional titles so changelogs, releases, and repository history stay readable.
4+
5+
## Format
6+
7+
```text
8+
type(optional-scope): Summary in imperative present tense
9+
```
10+
11+
Examples:
12+
13+
```text
14+
docs(readme): Clarify AI Project Context Protocol positioning
15+
feat(examples): Add backend API context kit
16+
fix(script): Handle Unicode output on Windows
17+
chore(metadata): Refresh repository SEO topics
18+
```
19+
20+
## Types
21+
22+
| Type | Use for |
23+
| :--- | :--- |
24+
| `feat` | New protocol capabilities, example kits, or user-facing assets. |
25+
| `fix` | Corrections to broken links, scripts, incorrect guidance, or unsafe defaults. |
26+
| `docs` | Documentation-only changes. |
27+
| `prompt` | Prompt templates, AI instructions, or agent guidance. |
28+
| `security` | Safe-publishing guidance, private-context handling, or vulnerability-reporting process. |
29+
| `ci` | GitHub Actions or repository validation automation. |
30+
| `chore` | Metadata, maintenance, cleanup, or non-user-facing updates. |
31+
32+
## Scopes
33+
34+
Common scopes include `readme`, `protocol`, `prompts`, `security`, `seo`, `examples`, `scripts`, `github`, and `agents`.
35+
36+
## Rules
37+
38+
- Use the imperative present tense: `Add`, `Clarify`, `Fix`, `Update`.
39+
- Capitalize the first word after the colon.
40+
- Do not end the title with a period.
41+
- Do not include secrets, private project names, customer names, or vulnerability details.
42+
- For breaking protocol changes, add `!` before the colon and describe the migration path in the PR body.

‎.github/workflows/validate.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Validate Repository
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- master
8+
- main
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
validate:
15+
name: Validate docs and metadata
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Check out repository
20+
uses: actions/checkout@v4
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.12"
26+
27+
- name: Run repository validation
28+
run: python scripts/validate-repo.py

‎AGENTS.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Nexus-APCP Agent Guide
2+
3+
This file gives AI coding assistants and automation agents the repository-specific rules for working on Nexus-APCP. Treat it as the first file to read before changing docs, prompts, scripts, metadata, or examples.
4+
5+
## Project Overview
6+
7+
Nexus-APCP is an open-source AI Project Context Protocol. The repository is a documentation and workflow kit, not a runtime application. Its purpose is to help developers give AI coding assistants stable project memory, task state, decision history, safety rules, and token-efficient communication patterns.
8+
9+
The public repository should remain safe to share. Real project context files, private architecture maps, secrets, generated prompt bundles, customer data, and security runbooks must not be committed unless they are sanitized templates.
10+
11+
## Primary Files
12+
13+
| Path | Role |
14+
| :--- | :--- |
15+
| `README.md` | Public product page, quick start, SEO surface, and first-time user orientation. |
16+
| `AI_PROJECT_CONTEXT_PROTOCOL.md` | Main protocol template for project identity, architecture, rules, and context. |
17+
| `AI_MAIN.md` | AI execution orchestrator and session checkpoint flow. |
18+
| `TASK_PROGRESS.yaml` | Current task state, sprint status, and repository maintenance progress. |
19+
| `DECISION_LOG_PROTOCOL.md` | Decision history and architecture intent protocol. |
20+
| `CAVEMAN_RULES.md` | Token-efficient communication rules. |
21+
| `AI_ASSISTANT_PROMPT_TEMPLATES.md` | Reusable prompts for common AI-assisted development scenarios. |
22+
| `WORKSPACE_SPECIFIC_DELIVERY_PROTOCOLS.md` | Domain-specific delivery gates and release expectations. |
23+
| `DOMAIN_SPECIFIC_GITIGNORE_PROTOCOLS.md` | Safe publishing patterns for different project domains. |
24+
| `scripts/apcp-gather.py` | Generates an AI-ready context bundle from core protocol files. |
25+
| `docs/SEO_CHECKLIST.md` | Repository SEO metadata and keyword source of truth. |
26+
27+
## Essential Commands
28+
29+
Run these from the repository root.
30+
31+
```bash
32+
python scripts/apcp-gather.py --caveman
33+
python scripts/validate-repo.py
34+
```
35+
36+
On Windows, the PowerShell checkpoint can also be used:
37+
38+
```powershell
39+
powershell -ExecutionPolicy Bypass -File scripts/checkpoint.ps1
40+
```
41+
42+
## Working Rules
43+
44+
- Keep changes scoped to the requested protocol, documentation, metadata, or script behavior.
45+
- Preserve the public/private boundary. Public templates are welcome; filled private project context is not.
46+
- Prefer durable wording over model-version-specific wording.
47+
- Keep repository-facing terminology consistent: `Nexus-APCP`, `AI Project Context Protocol`, `context engineering`, `AI-assisted development`, and `token optimization`.
48+
- Update `TASK_PROGRESS.yaml` when completing a visible repository maintenance task.
49+
- Update `docs/SEO_CHECKLIST.md`, `codemeta.json`, or `.github/repository-metadata.yml` when changing search-facing positioning.
50+
- Use concise comments only when they explain non-obvious validation, safety, or release behavior.
51+
52+
## Security Publishing Hygiene
53+
54+
This is a public repository. When working on security-related docs or fixes:
55+
56+
- Do not expose exploit paths, attack names, private infrastructure, or sensitive project identifiers in branch names, commit messages, PR titles, test names, or comments.
57+
- Use neutral functional wording, such as `improve input validation`, instead of naming the vulnerability class.
58+
- Keep vulnerability details in private reporting channels.
59+
- Never commit `PROMPT_READY.txt` generated from a private project.
60+
- Do not weaken `.gitignore`, security guidance, or private-context warnings without a clear replacement.
61+
62+
## Documentation Style
63+
64+
- First-time users should understand what the protocol does within the first screen of the README.
65+
- Prefer examples that are easy to adapt across Claude Code, Cursor, ChatGPT, Gemini, GitHub Copilot, local LLMs, and other agents.
66+
- Avoid claims that require live proof unless the repository provides the evidence.
67+
- Use tables for file maps, checklists for setup/review flows, and short code blocks for commands.
68+
- Keep public examples realistic but sanitized.
69+
70+
## Review Checklist
71+
72+
Before finishing a change, verify:
73+
74+
- Required public files still exist.
75+
- Markdown links added by the change are valid or intentionally external.
76+
- JSON files parse.
77+
- SVG assets parse as XML.
78+
- `scripts/apcp-gather.py --caveman` runs successfully.
79+
- The change does not add private context, secrets, generated prompt bundles, or sensitive security details.
80+
81+
## AI Adapter Files
82+
83+
Adapter files such as `CLAUDE.md`, `GEMINI.md`, `CURSOR.md`, `COPILOT.md`, and `CODEX.md` should stay short. They should point back to this file and mention only tool-specific startup behavior when necessary.

0 commit comments

Comments
 (0)