Imported from droxey/newproject (AGENTS.md). Install upstream with npx skills add droxey/newproject. Copyright stays with the author.

AGENTS.md — AI Agent & Copilot Guide

This project was generated from droxey/newproject.

Template Token System

Files in this repository may contain [[TOKEN_NAME]] placeholders. These are replaced at generation time by init.sh using sed. Remaining tokens are manual placeholders.

For AI Agents

• Do not treat [[TOKEN_NAME]] strings as code. They are template placeholders.
• Replace [[PROJECT_DESC]] and [[PROJECT_LOGO]] manually before committing.
• The Makefile provides common entry points: make help, make dev, make build, make deploy.
• See CONTRIBUTING.md for coding conventions.
• .openclaw/skill.json is a stub for OpenClaw skill registration. Populate the skills array with skill definitions as the project grows.

init.sh — AI Agent Usage Analysis

Current State: What Works ✅

Current State: What Doesn't Work ❌

Required Changes to Support Agent-Driven Invocation

RC1 — Support HTTPS clone (and env-var token injection)

Replace the SSH remote with an HTTPS remote that embeds the token, and accept GITHUB_TOKEN as an environment variable so agents can inject credentials via secrets rather than CLI flags.

# Use HTTPS with token for agent/CI environments
REPO_REMOTE="https://${GITHUB_TOKEN}@github.com/${REPO_PATH}.git"

# Accept env-var fallback so -t is optional when GITHUB_TOKEN is set
GITHUB_TOKEN="${GITHUB_TOKEN:-}"
# (then require_var still fires if both are absent)

RC2 — Add a --dry-run / -d flag

Skip create() and commit() when -d is passed; run only clone() and cleanup() against a local directory. This lets agents validate token replacement and file structure without touching GitHub.

# getopts addition
d) DRY_RUN=1 ;;

# main pipeline
if [ -z "$DRY_RUN" ]; then
    create && clone && cleanup && commit
else
    clone && cleanup
fi

RC3 — Accept an explicit output directory flag (-o)

Allow callers to specify exactly where the repo is cloned. Removes the $HOME/dev/repos heuristic.

o) CLONE_DIR="$OPTARG" ;;

RC4 — Emit a structured summary on success

After a successful run, write a key=value (or JSON) block to stdout so agents can parse results without screen-scraping prose.

# At end of successful pipeline
echo "REPO_URL=$REPO_URL"
echo "REPO_DIR=$REPO_DIR"
echo "FLAVOR=${FLAVOR:-default}"

RC5 — Fix -h to emit real usage text

h)
    echo "Usage: init.sh -n <name> -u <user> -r <repo> -t <token> [-m go|node|python|static] [-d] [-o <dir>]"
    exit 0
    ;;

RC6 — Replace force-push with a branch-safe push

# Replace: git push origin main --force
# With:
git push -u origin main

Prioritized TODO Checklist

Items are ordered by severity of agent-blocking impact. Security issues are addressed first.

• P0 — Security [B3] Move token out of process-argument vector: accept GITHUB_TOKEN env var; keep -t as an optional override that writes to the variable, not to the argument list directly.
• P1 — Correctness [B1] Switch git clone and remote URLs from SSH (git@github.com:) to HTTPS (https://github.com/) with token embedding, so the script works in any containerized or sandboxed agent environment.
• P1 — Correctness [B6] Replace git push origin main --force with git push -u origin main to respect branch protection rules and fine-grained PAT restrictions.
• P2 — Testability [B2] Add a -d (dry-run) flag that skips create() and commit() so agents (and humans) can validate token replacement locally without mutating GitHub state.
• P2 — Reliability [B5] Add a -o <dir> flag for an explicit clone destination; remove the $HOME/dev/repos auto-detection heuristic.
• P3 — Integration [B4] Accept all four credentials (GITHUB_TOKEN, GITHUB_USER, GITHUB_REPO, PROJECT_NAME) as environment variable fallbacks so agents using repository secrets don't need to reconstruct CLI flags.
• P3 — Integration [B7] Emit a structured KEY=VALUE summary block at the end of a successful run so agent orchestrators can parse REPO_URL and REPO_DIR without screen-scraping.
• P4 — UX [B8] Replace the -h stub with a real usage/help message listing all flags, defaults, and examples.
• P4 — UX [B10] Document clearly (here and in copilot-instructions.md) that [[PROJECT_DESC]] and [[PROJECT_LOGO]] require a manual post-generation step; optionally prompt for them interactively when not in dry-run mode.
• P5 — Maintenance [B9] Consider keeping init.sh in the generated repo (or replacing its content with a no-op stub) instead of deleting it, to allow re-generation or debugging.