Lindex — The Linux Codex Developer Field Guide

Linux Environment

Start with an environment you can explain and reproduce. Lindex uses Fedora Workstation or Fedora KDE as its reference, with Bash for shell examples. Most repository work carries across distributions; package installation and desktop integration need explicit platform details.

• Terminal and shell: open your desktop's terminal and use Bash for these examples. The terminal application displays the session; Bash interprets commands.
• Native Git: inspect and checkpoint the repository with the distribution's Git package and credential tools.
• Codex: install and authenticate using the Linux setup steps, then launch from the intended project.
• Project toolchain: follow the repository's documented runtime versions and dependency files.

cat /etc/os-release
bash --version
git --version

The release file identifies the distribution. A missing Git command is a prerequisite to resolve before making a checkpoint. Record the actual versions when reporting an environment-dependent failure.

Reference: Official Codex CLI guide.

Work From the Repository Root

Choose the repository root as a clear starting point for cross-project work. This makes manifests, tests and project rules easy to identify. A nested working directory does not automatically make every parent file invisible: instruction discovery and filesystem access follow their own rules.

In the example below, replace FieldGuide with an existing project under your home directory. $HOME expands to your home; the double quotes keep a path containing spaces together.

cd "$HOME/Projects/FieldGuide" && pwd
git rev-parse --show-toplevel
git status --short

If changing directory fails, stop and correct the path before running the remaining commands. If Git reports that the directory is not a repository, locate the intended checkout rather than initializing over an unfamiliar directory.

For a monorepo, name the package and shared modules involved. Use repository-relative paths in tasks, and ask Codex to identify the instructions it loaded. A working directory is an orientation choice; it is not a replacement for configured access restrictions.

Reference: AGENTS.md discovery, Codex sandbox boundaries.

Give Every Project an AGENTS.md

Use AGENTS.md for durable project instructions you can version and review. Document architecture, allowed technologies, commands, boundaries and the definition of done. It is an instruction file, not a guarantee that every fact about the project is held in context.

Codex checks global guidance and then project guidance from the root toward its working directory. Within a directory, AGENTS.override.md takes precedence over AGENTS.md; deeper guidance can override earlier guidance. Keep files concise and check the official discovery rules when using nested instructions or custom filenames.

Reference: AGENTS.md discovery.

This is a concrete template for a static guide like Lindex. Replace its commands and directory exclusions when adopting it for a different repository. The prose establishes expectations; configured permissions enforce access boundaries.

# AGENTS.md — Field Guide engineering rules

## Project and architecture
A static documentation website: HTML, CSS, vanilla JavaScript and local assets.
Keep the current navigation, design tokens, readable HTML and progressive enhancement.
Do not add React, a database, a backend or third-party tracking.

## Scope and Linux environment
Work inside this repository. Do not read sibling projects.
Use Bash examples, UTF-8 and LF. Label distribution-specific commands.
Inspect relevant code before editing. Preserve unrelated user changes.
Use elevated privileges only when an authorized operation actually requires them.
Do not read credentials, upload content, deploy or publish without task authorization.
Avoid vendor/, generated/ and private-data/ unless the task explicitly includes them.

## Commands for this example repository
Static audit: node scripts/qa-audit.js
Local preview: python3 -m http.server 8080 --bind 127.0.0.1
No production compilation step: upload the documented static files.
If this template is used elsewhere, replace these commands with that project's commands.

## Verification and quality
Run applicable checks and report actual results; identify pre-existing failures.
Verify keyboard navigation, focus, code copying and narrow-screen overflow for UI changes.
Keep input text out of executable HTML; never commit secrets.
Preserve local-file and subdirectory links. Keep assets local.
Update documentation when setup, behavior or deployment changes.

## Definition of done
Requested behavior works; unrelated behavior is preserved; the diff is reviewed.
Report changed files, executed checks, results and any remaining limitations.
Do not claim a check passed if it was not run.

Inspect the project instructions that apply to this task.
Report their source paths, required verification commands and any conflicting rules.
Do not modify files. If a rule assumes a command or directory that does not exist, identify it.

Give Codex Specifications, Not Vague Requests

A useful specification gives the agent a testable objective and enough context to avoid guessing. State the current behavior, desired behavior, relevant files, constraints and evidence you will accept. Keep architecture choices explicit when they matter.

Objective: fix the navigation overflow at 375px.
Scope: the existing header component and its styles.
Preserve: all links, search, focus visibility and the current visual identity.
Constraints: no new UI framework, dependencies or unrelated refactoring.
First inspect the implementation and identify the overflow cause.
Then make the smallest complete fix within this scope.
Verify at 375, 768, 1280 and 1920px; exercise keyboard navigation.
Report the diff, actual checks and any remaining limitation.

For a greenfield project, also specify the intended users, data flow, deployment target and minimum useful behavior. For an existing project, prefer established conventions over introducing another stack. Use the prompt builder to organize these details.

Use Staged Development

Break a substantial change into stages that each produce a reviewable result. Choose boundaries around behavior and dependencies: a schema or interface, core logic, integration, then end-to-end verification. A stage should be small enough to assess but complete enough to exercise.

1. Baseline: inspect manifests and tests; record existing failures and uncommitted work.
2. Contract: define inputs, outputs and error behavior before changing consumers.
3. Implementation: build one coherent slice with its relevant tests.
4. Integration: connect the slice to the real CLI, service or interface.
5. Verification: run applicable checks, inspect the diff and checkpoint the accepted result.

Implement the agreed parser change and its regression tests only.
Preserve the public return type and error contract.
Do not refactor the command-line interface yet.
Run the parser tests and the existing checks affected by this change.
Report the result and what the next integration stage still needs.

In a large repository, identify shared interfaces before splitting the work. Keep a short record of completed stages, decisions, remaining risks and exact checks. This gives a later session useful context without assuming it has every detail of earlier discussion.

Separate Analysis From Implementation

Use a read-only investigation when the cause or scope is unknown. Ask Codex to locate the entry point, trace the relevant data flow, inspect dependencies and report evidence. A plan should name the files likely to change and the check that will demonstrate the fix.

Investigate why the import command fails for a filename containing spaces.
Do not modify files yet. Work in this repository only.
1. Inspect the command entry point and subprocess invocation.
2. Trace how the input path is passed to the child process.
3. Reproduce the issue with disposable test data, if possible.
4. Separate observed evidence from hypotheses.
5. Propose a targeted fix and a regression test.
Report before implementation.

Review the result: does the evidence explain the symptom, or merely describe nearby code? Once you authorize a concrete implementation, let the agent carry out that scope without repeatedly seeking approval for routine reads. New destructive or external actions still need their appropriate authorization.

Make Codex Prove Its Work

Verification is an executed check tied to an acceptance criterion. Ask for the command, working directory, result and relevant evidence. Discover the repository's actual scripts first; a command named npm run type-check is useful only if that script exists.

For this static guide, the audit checks paths and JavaScript. The same command in an unrelated repository would have no meaning unless that project supplied the script.

node scripts/qa-audit.js
check_status=$?
printf 'Audit exit status: %s\n' "$check_status"

Capture $? immediately: it is the status of the most recently completed command. A zero exit status does not prove every requirement; read the output and check that the intended tests actually ran. Test and build commands can create files, execute project code or use external services, so establish their effects first.

Reference: GNU Bash manual.

Use Git as the Safety System

Inspect existing work before starting. A checkpoint is useful only when it preserves the intended files and excludes secrets or unrelated changes. Git does not automatically back up ignored or untracked files.

git status --short
git diff
git diff --staged
git log -5 --oneline
git branch --show-current

For a repository with a baseline commit, create a feature branch with a new, task-specific name. The branch separates history; it does not make an additional working directory.

git switch -c feat/import-paths

After reviewing the changes, stage only the relevant files. These paths illustrate an existing project; substitute the files you actually inspected. Review staged content before committing, and commit only when the staged changes are intentional.

git add -- src/importer.py tests/test_importer.py
git diff --staged

git commit -m "checkpoint: before import path changes"

If the working tree is already clean, there may be nothing to checkpoint. Record the current commit instead of manufacturing a change. After implementation, review both the unstaged and staged diff again. Use the recovery chapter if the result needs to be undone.

Give Codex Controlled Autonomy

Define what the task authorizes, where the agent may work and which actions need separate review. A scoped implementation can include reading files, making relevant edits and running known checks without a permission question at every step.

These are effect labels, not permission settings. A read-only command can still reveal sensitive data. A test can still modify a database. Avoid granting root privileges simply because an ordinary development command failed.

Reference: Codex sandbox boundaries.

Implement the agreed fix inside this repository and run its documented local checks.
Preserve unrelated edits. Do not access sibling projects or credentials.
Do not install system packages, change services, deploy or publish.
If a required action falls outside this scope, report the specific action and why it is needed.

Let Codex Debug Instead of Prescribing the Solution

Give the agent a reproducible symptom rather than a guessed remedy. For example, “the import fails when the path contains spaces” invites investigation; “add a sleep before opening the file” prescribes an unproven fix.

1. Symptom: record the exact command, expected result and actual failure.
2. Evidence: collect the relevant stack trace, versions and path/permission information.
3. Hypothesis: explain a cause that predicts the observed behavior.
4. Test: reproduce it using disposable inputs and change one variable.
5. Fix: address the demonstrated cause with a targeted change.
6. Verification: rerun the reproduction and add a regression test.

command -v python3
python3 --version
printf 'Working directory: %s\n' "$PWD"

If a command works in your terminal but not in an agent session, compare the actual working directory, interpreter and selected environment variables. Do not paste a complete credential-bearing environment dump. Consult Linux environment pitfalls before changing application code to compensate for a setup error.

Investigate this failure using the reproduction steps and redacted error below.
First establish the working directory, runtime version and relevant dependencies.
Inspect the implicated code. List observations separately from hypotheses.
Do not change permissions or install packages to hide the symptom.
Propose the smallest fix and explain how its regression test demonstrates the cause.

Web Development and Browser Verification

Test what users actually open. For a static site, check direct-file links if supported, local HTTP and the intended deployment path. For a framework application, use its documented development script and separately check its production build.

From the directory containing only the files you intend to serve, this Python 3 command starts a local static server. Use an unused port and stop the foreground server with Ctrl+C when finished.

python3 -m http.server 8080 --bind 127.0.0.1

Open http://127.0.0.1:8080. The bind address limits the listening interface to loopback; it does not add authentication. Python's simple HTTP server is for local development, not production deployment.

Reference: Python local HTTP server.

• Check 375, 768, 1280 and 1920px widths, including long code blocks and tables.
• Use the keyboard: menus, focus return, search, forms and copy controls must work.
• Inspect console and network errors; exercise invalid input and missing-data paths.
• Verify the changed behavior in the target browser rather than relying only on a screenshot.

Lindex's production files remain static. cPanel serves HTML, CSS, JavaScript and local assets; it does not need this Python process or a Node server.

Recover Failed Work Deliberately

When repeated fixes add complexity without explaining the failure, pause implementation and inspect the accumulated diff. Preserve the current work before choosing a recovery action. Do not apply a whole-repository reset simply because a second attempt failed.

git status --short
git diff --stat
git diff
git diff --staged
git log -5 --oneline

Reference: Git restore, Git revert.

Record the failed approach, its evidence and the revised constraints. Resume from a known state with a new hypothesis. A useful handoff preserves learning; clearing a conversation does not repair files.

Maintain Project Documentation

Update documentation when a change alters setup, commands, architecture or behavior. An obsolete test command in AGENTS.md can misdirect the next task just as readily as a broken script.

• README: supported prerequisites, setup and the shortest path to running the project.
• Architecture notes: important interfaces, data flow and decisions with their tradeoffs.
• AGENTS.md: current boundaries and executable verification instructions.
• Deployment: exact artifacts, environment requirements and release checks.

Summarize this task for the next engineering session:
- Objective and authorized scope
- Files and behaviors changed
- Decisions and constraints that still apply
- Checks actually executed and their results
- Failed approaches and what they taught us
- Remaining work and the next concrete verification step
Keep this concise; exclude secrets and unrelated conversation.

For Linux setup, state the distribution and shell when they affect a command. Record project versions from manifests or toolchain files rather than labeling whichever version happened to be installed as universally required.

Use Parallel Agents Selectively

Delegate only when tasks are sufficiently independent to justify coordination. Define each task's allowed files, shared interfaces and verification responsibilities. Parallel editing of the same files can overwrite work or produce incompatible assumptions on any operating system.

A Git worktree provides another working directory with its own checkout. Branches in one working directory do not provide that filesystem separation. Worktrees still share repository data and may share external services, caches or ports.

Reference: Git worktrees.

git worktree list

Use the command below only after choosing an authorized, unused destination and a new branch name. It creates a sibling checkout, so it is unsuitable when the task is restricted to the current directory.

git worktree add -b docs/import-guide ../field-guide-docs

Have one person or agent integrate the results and run checks across the combined change. Keep a small sequential task sequential. Consult the current Codex interface documentation before relying on a particular delegation feature.

Use Codex as Different Engineering Specialists

A specialist prompt gives a review a focus. It does not certify the result. Define the question, scope and evidence you need, then judge the findings against the code and tests.

• Architect: dependencies, contracts, state boundaries and maintainability.
• Bug investigator: reproducible causes and competing hypotheses.
• Security reviewer: trust boundaries, inputs, secrets and privileges.
• QA engineer: regression coverage, edge cases and realistic failure paths.
• Performance engineer: measured bottlenecks and comparable benchmarks.
• Accessibility reviewer: semantics, keyboard access and assistive technology behavior.
• Release engineer: artifacts, deployment prerequisites and verification.
• Refactoring specialist: simpler structure with observable behavior preserved.

Act as a release reviewer for this Linux application.
Inspect the documented build and release process; do not publish anything.
Identify the target environment, generated artifacts and required runtime dependencies.
Separate verified findings from assumptions.
Report blockers with file locations and a concrete check for each proposed correction.

The prompt library retains all eight specialist roles. Use a task-specific scope instead of treating the role name as permission to rewrite the project.

Establish a Professional Completion Contract

Agree what completion means before implementation. Apply checks that fit the repository and task: a static guide has different build requirements from a desktop package or database service. A checklist score supports review; it cannot certify production safety.

Before reporting this task complete:
1. Verify the requested behavior and relevant error paths.
2. Check that unrelated behavior and user edits were preserved.
3. Remove accidental scaffolding or incomplete implementation from the delivered scope.
4. Run applicable formatting, static checks and tests; report actual results.
5. Build or package when the project requires it.
6. Review security, accessibility and runtime implications relevant to the change.
7. Inspect the final diff, including staged changes and new files.
8. Update affected documentation.
9. State checks not run and remaining limitations.
10. Do not deploy or publish unless that action is authorized.

Report: summary; changed files; executed checks and results; remaining limitations.

Use the completion checklist as a reminder, then attach the evidence to the actual change. A truthful blocked check is more useful than an unsupported claim of success.