Skip to content

SOFTWARE_AND_PLUGIN_REQUIREMENTS.md

Latest commit

 

History

History
146 lines (104 loc) · 7.95 KB

SOFTWARE_AND_PLUGIN_REQUIREMENTS.md

File metadata and controls

146 lines (104 loc) · 7.95 KB
Raw

Software And Plugin Requirements

This template is mostly Markdown, project rules, and local Codex skills. It is intentionally lightweight.

For a plain-language status table of apps, connectors, and optional tools, read APP_AND_CONNECTOR_USAGE.md.

Minimum Setup

Requirement Link Plain-English Purpose
Codex Codex or Codex CLI Runs the agent and reads the local project files.
GitHub account Sign up Lets you clone, share, and update the template.
Git Download Git Tracks changes and lets you pull updates.
Terminal or shell Apple Terminal, Windows Terminal, Git Bash, or Linux terminal Runs simple setup and privacy-check commands.
Python 3 Download Python Runs the local helper scripts such as runtime preflight, cognitive protocol checks, skill evals, and connector checks.

Strongly Recommended

Tool Link Use
GitHub Desktop Download Beginner-friendly clone, commit, pull, and push.
GitHub CLI gh Install Helpful for checking repo access and GitHub Actions.
ChatGPT Codex Connector GitHub App Lets Codex inspect repository files through the GitHub connector.

Optional For Research Work

Tool Link Use
Obsidian Download Reads the Markdown knowledge layer like a linked notebook. Open knowledge-base/ as your Obsidian vault. Do not open the repository root.
LibreOffice Download Free .docx opening and rendering.
Microsoft Word Word Final document editing and comments.
Poppler Project site Optional PDF/page-image checks for generated documents.
Node.js / npm Node.js Optional. Needed only if you choose CLI browser automation workflows that depend on npm/npx.
Playwright Playwright Optional. Browser automation for read-only checks, local previews, or UI verification.
MarkItDown Microsoft MarkItDown Optional. Converts documents into Markdown for source review or knowledge-base ingestion.
ChatGPT or another LLM chat ChatGPT Optional. Can review a local prompt generated by scripts/build_external_review_bundle.py. It is advisory only.
Claude Code Claude Code Optional. Can be used through scripts/claude_independent_review.py as one privacy-gated external reviewer runner if the user has access. It is not required by this template.
ChromaDB + sentence-transformers ChromaDB / Sentence Transformers Optional. Needed only for neural vector retrieval via requirements-vector.txt.

Not Needed At First

  • OpenAI credential
  • Node.js
  • npm packages
  • Python packages beyond the standard library
  • external MCP servers
  • browser automation
  • MarkItDown

Python 3 itself is needed for the local scripts if you want runtime preflight, skill evals, connector checks, or cognitive protocol checks. Extra Python packages are not needed for the default workflow.

The formal-delivery helpers are also standard-library Python scripts:

  • scripts/material_passport.py
  • scripts/pre_delivery_lock.py
  • scripts/formal_delivery_guard.py

The authorial-voice helper is also a standard-library Python script:

  • scripts/authorial_voice_scan.py

It is not an AI detector. It flags risky task framing, prompt residue, generic AI-style prose, disclosure-hiding requests, and possible overclaiming so the agent can revise towards clearer authorial judgement and evidence-led style.

The style and execution-evidence helpers are also standard-library Python scripts:

  • scripts/style_fingerprint_scan.py
  • scripts/skill_execution_receipt.py
  • scripts/document_quality_check.py
  • scripts/self_review_loop_check.py
  • scripts/claim_ledger_lite_check.py
  • scripts/visible_output_qa_check.py
  • scripts/borrowed_pattern_boundary_lint.py

They do not require an external model. They make repeated style templates, missing skill evidence, shallow document-quality reviews, shallow self-review loops, claim-boundary gaps, missing visible-output checks, and unsafe borrowed style/workflow language visible before delivery.

Install extra tools only when your project workflow clearly needs them.

Beginner Setup Checklist

  1. Install Codex or open Codex in ChatGPT.
  2. Create a GitHub account.
  3. Install Git.
  4. Install or confirm Python 3 is available if you plan to run the local scripts.
  5. Clone or download this repository.
  6. Copy RESEARCH_PROJECT_BRIEF_TEMPLATE.md to RESEARCH_PROJECT_BRIEF.md.
  7. Choose a project profile from PROJECT_TYPE_PROFILES.md.
  8. Fill placeholders slowly. Use TO CONFIRM when unsure.
  9. Open the folder in Codex.
  10. Ask Codex to read AGENTS.md, PROJECT_AGENT_PREFERENCES.md, RESEARCH_PROJECT_BRIEF.md, PROJECT_TYPE_PROFILES.md, and .agents/skills/.
  11. Run the privacy check before sharing:
./scripts/privacy_check.sh

Common Confusions

Git and GitHub are different.

  • Git is the local version-control tool.
  • GitHub is the website where the repository can live.

Codex and GitHub Connector are different.

  • Codex runs the agent.
  • The GitHub Connector lets Codex inspect GitHub repository content after authorisation.

Obsidian is optional.

  • The project works without it.
  • It just makes Markdown notes easier to browse.
  • Open knowledge-base/ as your Obsidian vault. Do not open the repository root.
  • For a cleaner personal notebook, copy templates/obsidian-vault/ outside the repository and open the copy.

Python and Python packages are different.

  • Python 3 runs the built-in scripts.
  • Extra Python packages are not needed unless you choose optional extensions.

SQLite/local retrieval and neural vector retrieval are different.

  • scripts/build_agent_index.py and scripts/local_retrieval_search.py use local Python/SQLite workflows.
  • scripts/build_vector_index.py and scripts/vector_retrieval_smoke_test.py require optional vector packages from requirements-vector.txt.
  • Retrieval finds candidate files. It does not prove source support.

Claude Code and the Claude review wrapper are different.

  • Claude Code is one optional external reviewer path.
  • scripts/claude_independent_review.py is the local wrapper that checks privacy, applies a timeout, writes a review report, and reminds users that Claude feedback is advisory only.
  • Users without Claude Code can run scripts/build_external_review_bundle.py and paste the generated EXTERNAL_REVIEW_PROMPT.md into a separate Codex, ChatGPT, Claude, Gemini, or human review process.

Authorial voice and AI detector evasion are different.

  • The kit can help remove prompt residue, generic phrasing, vague claims, and inflated style.
  • It must not promise lower detector scores, bypass AI detection, hide AI-use disclosure, or add random stylistic noise.

Style fingerprint scan and AI detection are different.

  • The scan flags repeated surface templates such as rather than, not...but, 不是...而是, and 而不是.
  • It does not decide whether text was written by AI.
  • It should protect clarity and authorial judgement, not remove legitimate academic scope distinctions.

Skill execution receipts and quality approval are different.

  • Receipts show that a required skill produced an evidence artifact.
  • They do not prove that the evidence is academically sufficient, truthful, non-fabricated, or fully acted on.