Architecting Repos

Given a raw project folder:

1. Read manifest files (package.json, requirements.txt, pyproject.toml, go.mod) to detect stack.
2. Scan for existing config files — never assume they're missing.
3. Generate/merge the five core deliverables (see Outputs below).
4. Report what was created, what was merged, and what commands were discovered vs. assumed.

Example invocation: "Organize this repo for GitHub" → run full Workflow.

Progress:
- [ ] Step 1: Detect language/framework from manifest files
- [ ] Step 2: Inventory existing structure (don't duplicate or erase)
- [ ] Step 3: Scaffold missing directories (.github/workflows, .github/ISSUE_TEMPLATE, assets/)
- [ ] Step 4: Write/merge .gitignore
- [ ] Step 5: Write .pre-commit-config.yaml with stack-appropriate linters
- [ ] Step 6: Write .github/workflows/quality-gate.yml using discovered build/test commands
- [ ] Step 7: Write .github/ISSUE_TEMPLATE/bug_report.yml (form-based)
- [ ] Step 8: Assemble README.md as interactive dashboard
- [ ] Step 9: Summarize changes to user

Step 1 — Detect stack: Open manifest files directly. Identify language, framework, package manager, and existing scripts (e.g., npm run test, pytest, go build). These become the only commands used in CI later.

Step 2 — Inventory: Check for existing .gitignore, README.md, .github/ folder, .pre-commit-config.yaml. Read contents fully before touching anything.

Step 3 — Scaffold: Create only what's missing:

.github/workflows/
.github/ISSUE_TEMPLATE/
assets/

Step 4 — .gitignore: Append missing ecosystem-specific rules under a clearly commented section (e.g., # --- Added by repo architect ---). Never delete existing lines.

Step 5 — Pre-commit config: Map detected stack to formatter/linter:

• Node/JS/TS → Prettier + ESLint
• Python → Black + Ruff/Flake8
• Go → gofmt + go vet

Step 6 — CI workflow: Use only commands found in Step 1's manifest scripts. If no test command exists, include a lint-only job and note the gap in the summary — do not invent a test command.

Step 7 — Issue template: YAML form with fields: description, reproduction steps, expected vs actual behavior, environment, severity dropdown.

Step 8 — README: Structure as:

• Title + badges (build status, license, version — only if CI/license actually exist)
• One-paragraph description (factual, no buzzwords)
• Mermaid architecture diagram (only if multi-module structure justifies it)
• <details> dropdowns for: Installation, Usage, Configuration, Contributing
• Status grid table (feature/module vs. status)

Step 9 — Summary: List every file created vs. merged, and flag any assumptions that need user confirmation (e.g., "no test script found — quality-gate.yml runs lint only").

Example 1: Input: Folder with package.json (scripts: build, test, lint), src/, no other config. Output:

• .gitignore created with Node-specific rules (node_modules/, .env, dist/)
• .pre-commit-config.yaml created with Prettier + ESLint hooks
• .github/workflows/quality-gate.yml created running npm run lint and npm run test (commands pulled directly from package.json)
• README.md created with install (npm install), usage (npm run build), and badge for build status
• Summary: "All commands sourced from package.json scripts. No existing config files found — nothing merged, everything created fresh."

Example 2: Input: Python project with requirements.txt, existing .gitignore (only has *.pyc), no README. Output:

• .gitignore merged: existing *.pyc line kept, added __pycache__/, .env, venv/, .pytest_cache/ under a marked new section
• .pre-commit-config.yaml created with Black + Ruff
• quality-gate.yml created — but no test command found in any manifest, so workflow runs lint/format-check only
• Summary flags: "No test runner detected (no pytest/tox config found). CI includes lint stage only — add a test command if one exists."