Oss Ready

OSS Ready

Transform a project into a professional open-source repository with standard community files and GitHub templates.

Two terms are used throughout:

• Additive edit: on a file that already exists, add only missing sections or lines. Never replace, reword, translate or delete the user's content.
• Placeholder: a match of PH='\[(YEAR|COPYRIGHT HOLDER|INSERT [A-Z ]+)\]|TODO|TBD|FIXME' in a created file, or in a line the run added to an existing file.

Repo Sync Before Edits (mandatory)

Prerequisites: a git repository on a named branch with an origin remote. Run the block in references/repo-sync.md once, before Step 0. It stops at the first failure:

1. Stop when git rev-parse --git-dir fails (not a git repository).
2. Stop when git symbolic-ref --quiet --short HEAD fails (detached HEAD), before any stash or sync.
3. Stop and ask the user when git remote get-url origin fails.
4. If git status --porcelain prints a line, stash with git stash push -u.
5. Run git fetch origin && git pull --rebase origin "$branch".
6. Restore the stash with git stash pop --index.

On a non-zero exit, print the final report with BLOCKED and the recovery commands the block printed. Never discard changes. If the only failure is the missing origin and the user approves continuing, go to Step 0 and list Repo Sync skipped (no origin) under Uncertainty:.

Workflow

Before Step 0, check references/edge-cases.md. If a case matches the repo, handle it as written there first.

Step 0: Create Feature Branch

1. Read the current branch: git branch --show-current.
2. Read the default branch: git symbolic-ref --short refs/remotes/origin/HEAD, without the origin/ prefix. If that fails, use main, or master when only master exists.
3. If the current branch is not the default branch and its name contains oss, stay on it and go to Step 1.
4. Choose the prefix feature/ when git branch -a --format='%(refname:short)' lists more feature/ than feat/ branches; otherwise feat/.
5. If <prefix>oss-ready exists, ask the user to reuse it or to give another name. Never reset an existing branch.
6. Run git switch -c <prefix>oss-ready, or git switch <name> to reuse. If it fails, stop with BLOCKED.

Step 1: Analyze Project

Record the stack, purpose, existing files, license, repo URL, README language, visibility and fill values, as references/file-specs.md → Analysis values describes. Ask for the security and conduct contacts in one question. If no stack is detectable, ask which stack to assume.

Step 2: Create/Update Core Files

Write README.md and CONTRIBUTING.md from the Step 1 values. Copy LICENSE from assets/LICENSE-MIT unless one exists or the user names another license. Copy CODE_OF_CONDUCT.md (Contributor Covenant 2.0) and SECURITY.md from assets/. Replace each placeholder with its Step 1 value. Section lists and per-file rules: references/file-specs.md.

Take every usage example from the repo's code, scripts or --help output. Never invent a command or contact. A section with no source in the code is left out and listed under Manual review.

Step 3: Create GitHub Templates

Copy each missing file from assets/.github/: ISSUE_TEMPLATE/bug_report.md, ISSUE_TEMPLATE/feature_request.md, PULL_REQUEST_TEMPLATE.md. Keep every existing file and workflow under .github/ unchanged.

Step 4: Create Documentation Structure

Create each missing file. Skip rules and contents: references/file-specs.md → docs/.

docs/
├── ARCHITECTURE.md    # System design, components
├── DEVELOPMENT.md     # Dev setup, debugging
├── DEPLOYMENT.md      # Production deployment
└── CHANGELOG.md       # Version history (skip when a root CHANGELOG.md exists)

Step 5: Update Project Metadata

Add each missing license, description and repository field to the root manifest. Never overwrite a field that has a value. Parse the file after the edit. Per-stack fields and parse commands: references/file-specs.md → Project metadata.

Step 6: Ensure .gitignore

Append each missing pattern for the stack from references/file-specs.md → .gitignore. Check one pattern with grep -qxF '<pattern>' .gitignore. Never remove a line.

Step 7: Verify and Report

1. Run every Acceptance Criteria check. Record pass, fail or not applicable with its reason.
2. Set PH as defined in Placeholder above. Run the placeholder grep on each created file: grep -nE "$PH" <file>.
3. Run it on the lines added to each updated file: git diff -U0 -- <file> | grep -E '^\+' | grep -E "$PH".
4. Run git status --porcelain. Confirm that no line starts with D or D .
5. Print the final report.

Do not commit or push. The user reviews and commits the branch.

Step Completion Reports

After each of Steps 1-7, print a report in this format (example: references/final-report.md):

◆ [Step Name] ([step N of 7] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Name each check after what the step validates. Step 0 gets no report. If Step 0 or 1 fails, stop with BLOCKED. If one of Steps 2-6 reports FAIL or PARTIAL, continue; the run ends PARTIAL. Step 7 runs whenever Step 2 started.