v1.3.1 to v1.4.0

- version: 1.3.1

- ## Repo Sync Before Edits (mandatory)

- Before creating/updating/deleting files in an existing repository, require a named branch and use the stash-first sync flow below. A detached HEAD stops before any stash or sync operation:

- ```bash

- branch="$(git symbolic-ref --quiet --short HEAD)" || {

- echo "✗ Detached HEAD — stop before stashing or syncing."

- exit 1

- }

- dirty=0

- if [ -n "$(git status --porcelain)" ]; then

- git stash push -u -m "pre-sync: ${branch} $(date +%Y-%m-%dT%H:%M:%S)" || {

- echo "✗ Could not stash local changes — resolution stopped."

- echo " Recovery: inspect git status; do not discard the working tree."

- exit 1

- }

- dirty=1

- fi

- if ! git fetch origin || ! git pull --rebase origin "$branch"; then

- echo "✗ Repository sync failed — resolution stopped."

- if [ "$dirty" -eq 1 ]; then

- echo " Your changes remain safe in the stash."

- echo " Recovery: git stash list"

- echo " git stash show -p stash@{0}"

- fi

- exit 1

- fi

- if [ "$dirty" -eq 1 ]; then

- git stash pop --index || {

- echo "✗ Stash restore failed — resolution stopped; your changes remain safe in the stash."

- echo " Recovery: git stash list"

- echo " git stash show -p stash@{0}"

- echo " git checkout stash@{0} -- <path>"

- echo " git stash pop --index stash@{0}"

- exit 1

- }

- fi

- ```

- ## Workflow

- > Before proceeding, check **Edge Cases** below for a non-MIT LICENSE, a monorepo, no detectable language, a private/internal repo, or a dirty/detached HEAD — handle the matching case first if it applies.

- ### 0. Create Feature Branch

- Before making any changes:

- 1. Check the current branch - if already on a feature branch for this task, skip

- 2. Check the repo for branch naming conventions (e.g., `feat/`, `feature/`, etc.)

- 3. Create and switch to a new branch following the repo's convention, or fallback to: `feat/oss-ready`

- ### 1. Analyze Project

- Identify:

- - Primary language(s) and tech stack

- - Project purpose and functionality

- - Existing documentation to preserve

- - Package manager (npm, pip, cargo, etc.)

- ### 2. Create/Update Core Files

- **README.md** - Enhance with:

- - Project overview and motivation

- - Key features list

- - Quick start (< 5 min setup)

- - Prerequisites and installation

- - Usage examples with code

- - Project structure

- - Technology stack

- - Contributing link

- - License badge

- **CONTRIBUTING.md** - Include:

- - How to contribute overview

- - Development setup

- - Branching strategy (feature branches from main)

- - Commit conventions (Conventional Commits)

- - PR process and review expectations

- - Coding standards

- - Testing requirements

- **LICENSE** - Default to MIT unless specified. Copy from `assets/LICENSE-MIT`.

- **CODE_OF_CONDUCT.md** - Use Contributor Covenant. Copy from `assets/CODE_OF_CONDUCT.md`.

- **SECURITY.md** - Vulnerability reporting process. Copy from `assets/SECURITY.md`.

- ### 3. Create GitHub Templates

- Copy from `assets/.github/`:

- - `ISSUE_TEMPLATE/bug_report.md`

- - `ISSUE_TEMPLATE/feature_request.md`

- - `PULL_REQUEST_TEMPLATE.md`

- ### 4. Create Documentation Structure

- └── CHANGELOG.md # Version history

- ### 5. Update Project Metadata

- Update package file based on tech stack:

- - **Node.js**: `package.json` - name, description, keywords, repository, license

- - **Python**: `pyproject.toml` or `setup.py`

- - **Rust**: `Cargo.toml`

- - **Go**: `go.mod` + README badges

- ### 6. Ensure .gitignore

- Verify comprehensive patterns for the tech stack.

- ### 7. Present Checklist

- After completion, show:

- - [x] Files created/updated

- - [ ] Items needing manual review

- - Recommendations for next steps

- After completing each major step, output a status report in this format:

- ◆ [Step Name] ([step N of M] — [context])

- [Check 2]: √ pass (note if relevant)

- [Check 3]: × fail — [reason]

- [Check 4]: √ pass

- Adapt the check names to match what the step actually validates. Use `√` for pass, `×` for fail, and `—` to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

- ### Analysis (step 1 of 7)

- ```

- ◆ Analysis (step 1 of 7 — project profiling)

- ··································································

- Language detected: √ pass — TypeScript (primary)

- Project type identified: √ pass — CLI tool

- Existing docs found: √ pass — README.md (partial), no LICENSE

- [Criteria]: √ 3/3 met

- ____________________________

- Result: PASS

- ```

- Repeat this format for each subsequent step — Core Files, GitHub Templates, Documentation, Project Metadata, .gitignore, Checklist — adapting the check names to what that step actually validates. Steps 5 and 6 carry acceptance criteria of their own, so a run that reports complete without them has skipped verifiable work. Step 0 sets up the branch and gets no report.

- ## Guidelines

- - Adapt to project's actual tech stack

- - Include working examples from the actual codebase

- The skill is complete when every item below can be verified with `test -f`, `grep`, or a quick visual check. Treat this as a checklist the agent must assert before reporting success.

- - [ ] `LICENSE` exists at repo root and contains a valid SPDX identifier (e.g., `MIT`, `Apache-2.0`). Verify: `grep -E "MIT License|Apache License" LICENSE`.

- - [ ] `README.md` exists, is at least 40 lines, and includes sections for Installation, Usage, and License. Verify: `grep -iE "^#+ (install|usage|license)" README.md | wc -l` returns >= 3.

- - [ ] `CONTRIBUTING.md` exists and references the issue tracker plus a branching/PR workflow. Verify: `grep -iE "issue|pull request|branch" CONTRIBUTING.md`.

- - [ ] `CODE_OF_CONDUCT.md` exists and mentions the Contributor Covenant. Verify: `grep -i "contributor covenant" CODE_OF_CONDUCT.md`.

- - [ ] `SECURITY.md` exists and lists at least one vulnerability-reporting contact (email or form URL). Verify: `grep -E "@|https?://" SECURITY.md`.

- - [ ] `.github/ISSUE_TEMPLATE/bug_report.md` and `.github/ISSUE_TEMPLATE/feature_request.md` both exist with YAML frontmatter (`name:`, `about:`).

- - [ ] `.github/PULL_REQUEST_TEMPLATE.md` exists and contains a checklist (`- [ ]`).

- - [ ] `.gitignore` exists and excludes the language-appropriate build/temp artefacts (e.g., `node_modules/`, `dist/`, `__pycache__/`, `target/`).

- - [ ] Project metadata file (`package.json`, `pyproject.toml`, `Cargo.toml`, or `go.mod`) declares `license`, `description`, and `repository` fields where the format supports them.

- - [ ] No previously committed files were deleted; only additions and non-destructive enhancements were made.

- After a successful run on a TypeScript CLI project that started with only a partial `README.md`, the agent emits a final report shaped like this:

- ◆ OSS Ready summary (7 of 7 steps complete)

- ··································································

- Files created:

- √ LICENSE (MIT)

- √ CONTRIBUTING.md (33 lines)

- √ CODE_OF_CONDUCT.md (Contributor Covenant 2.1)

- √ SECURITY.md (reporting via security@example.com)

- √ .github/ISSUE_TEMPLATE/bug_report.md

- √ .github/ISSUE_TEMPLATE/feature_request.md

- √ .github/PULL_REQUEST_TEMPLATE.md

- √ docs/ARCHITECTURE.md, DEVELOPMENT.md, DEPLOYMENT.md, CHANGELOG.md

- Files updated:

- √ README.md (+ Quick Start, Usage, License badge)

- √ package.json (license, repository, keywords)

- √ .gitignore (added dist/, .env)

- Acceptance criteria: √ 10/10 met

- Manual review needed:

- - Confirm SECURITY.md contact email is monitored

- - Add real maintainer names to CODE_OF_CONDUCT enforcement section

- ____________________________

- Result: PASS

- The agent must list the manual-review items explicitly so the user can finish what cannot be automated. Assert that the file tree printed by the agent matches what is actually on disk before declaring PASS.

- The skill should detect and handle these inputs explicitly rather than fail silently:

- - **Existing LICENSE with a non-MIT identifier** — never overwrite. Read it, log the detected license, and skip the LICENSE step.

- - **Monorepo with multiple `package.json` files** — update only the root metadata file unless the user names a sub-package.

- - **Repo with no detectable language** (empty repo or only docs) — pause and ask the user which template stack to assume.

- - **Existing `CODE_OF_CONDUCT.md` or `SECURITY.md`** — diff against the template; only append a missing section, never replace user content.

- - **Private/internal projects** — confirm with the user before adding public-facing files like SECURITY.md or community templates.

- - **Pre-existing `.github/` workflows or templates** — preserve them; merge only the missing files.

- - **Non-English README** — keep the existing language; do not translate, only add structurally missing sections in the same language.

- - **Detached HEAD** — stop before stashing or syncing; never force changes onto an unstable branch.

- - **Dirty working tree** — use the stash-first Repo Sync flow above. If stashing, syncing, or restoring fails, stop and use the printed recovery commands; never discard changes.

- ## Assets

- Templates in `assets/`:

- - `LICENSE-MIT` - MIT license template

- - `CODE_OF_CONDUCT.md` - Contributor Covenant

- - `SECURITY.md` - Security policy template

- - `.github/ISSUE_TEMPLATE/bug_report.md`

- - `.github/ISSUE_TEMPLATE/feature_request.md`

- - `.github/PULL_REQUEST_TEMPLATE.md`