Skip to content

AGENTS.md

Latest commit

 

History

History
157 lines (127 loc) · 6.81 KB

AGENTS.md

File metadata and controls

157 lines (127 loc) · 6.81 KB
Raw
title shelltutor Agents Contract
category governance
component agents-contract
status active
version 0.1.0
last_updated 2026-07-14
tags
agents
claude
codex
authority
boundary
priority high

AGENTS.md — shelltutor

This file provides Codex, Claude Code, and other coding agents with local guidance for the shelltutor repository — the directory holding this file.

A parent Jefahnierocks workspace contract may exist as an AGENTS.md alongside this repository (typically when shelltutor is checked out under a jefahnierocks/ workspace root). When present, that parent contract also applies. Rules in that file and rules restated here are stated on shelltutor's own authority, on Jefahnierocks's own authority — they are not inherited from a parent organization at runtime. Where a parent organizational spec is the original source of a rule, the parent is cited as a reference, not a runtime authority.

When guidance conflicts, the closest local rule wins inside this repository, while the Jefahnierocks workspace boundary still applies.

Identity

shelltutor is a single-file interactive tutor for the Unix shell. The project's defining property is that it is user-agnostic: no operator name, distro, hostname, theme, home-directory layout, or pre-existing shell setup is assumed by the script or by any document in this repository.

When a change would couple the tutor to a specific user, host, or operator-private environment, pause and propose a portable alternative before applying.

Scope

Stay inside this repository for normal work. Reading or modifying material outside the repository root requires explicit user scope expansion.

The prior-art repository at fedora-top:~/Projects/shelltutor is intake provenance only. Do not treat its current state as ambient truth, and do not silently re-import its user-specific surfaces (wyn-setup/, theme branding, operator-named comments).

Agent Roles

  • Builder — Implement scoped changes to the tutor script, lessons, and documentation.
  • Maintainer — Keep portability claims, lesson surface, and docs coherent across changes.
  • Reviewer — Surface portability regressions, hidden host assumptions, unsafe shell idioms, lessons that would mislead beginners, and any re-introduction of user-specific content.
  • Operator — Run the tutor locally during validation; prefer reproducible invocations over interactive demos.

Authority Levels

  • Routine work — Read and edit files inside this repository, run the tutor for validation, edit lessons, update documentation, and adjust portability shims.
  • Sensitive work — Change the tutor's safety surface (file writes, network access, privilege handling, sandbox boundaries) only when the user request clearly calls for it.
  • Restricted work — Do not introduce dependencies that require installation outside bash and a standard POSIX userland; do not access files outside this repository during normal operation; do not perform account, billing, or credential changes.

When authority is unclear, ask before acting.

Work Rules

  • Use Conventional Commits for any commits created (type(scope): description).
  • Keep each change focused and inspectable; one coherent change per commit.
  • Preserve linear history; do not rewrite unrelated history.
  • The tutor's own code must not write outside its configured sandbox, must not request elevated privileges, and must not reach the network.
  • Treat anything that requires a specific username, hostname, distro, or shell theme as a portability bug.
  • Lessons must be runnable end-to-end on a clean Linux or macOS terminal without prerequisite installation beyond bash.

Validation

  • Run the tutor (./shelltutor) and complete at least the lesson surface affected by a change.
  • For portability changes, validate on both Linux and macOS when possible, or state which surface was tested and which is pending.
  • For documentation-only changes, check links, paths, and that frontmatter fields remain accurate.

Active Artifacts

Read these before any substantive change. They are the durable record of prior decisions and ongoing direction; not reading them means re-deriving context that already exists.

  • STATUS.md — current status-of-record; project.yaml is its machine-readable meta-inventory projection and must not outrun it.
  • audit/2026-07-14/findings.md — resolved F-009 portability regression and the Bash 3.2/Bash 5.3 validation boundary.
  • audit/2026-05-21/SUMMARY.md — first audit cycle (Agentic Architecture Audit Spec v3.1). At that snapshot, seven findings (F-001–F-007) were smoke-tested confirmed-current at revision e6257aa; follow-on work closed them. The cycle proposed fitness functions FF-001–FF-007.
  • profile/2026-05-21/project_profile.yaml and profile-discovery.md — first profile snapshot (Project Profile Discovery Directive v1.2).
  • ROADMAP.md Phase 3 — completed curriculum redesign spec: five mastery-gated stages, vimtutor-prerequisite framing, 3/3 recall + task gates.
  • docs/audit/references/ — verified research reference set (six docs, v0.2.0; see README.md for the index and verification notes). shell-research.md is the curriculum basis for Phase 3 (12 concepts / 6 units). The other five — pty-harness-research.md, simulation-evidence-model.md, persona-simulation-research.md, practice-shell-hardening-research.md, educational-design-research.md — underpin the FF-006 implementation ladder (static smoke / PTY lesson flow / multi-persona depth).
  • docs/audit/directives/agentic-architecture-audit-v3.1-package/ — authority texts the profile and audit were generated against; not modified, treated as an in-repo snapshot.

If a change touches one of the findings or fitness functions, cite the ID in the commit body (e.g., refactor(welcome): narrow sandbox claim (F-002)).

Secrets And Sensitive Data

Do not commit secrets, credentials, account identifiers, private financial data, or sensitive personal data. The tutor is public and reads from a public repository; it must remain safe to run on any stranger's machine.

Use placeholders in examples. If sensitive data is found in tracked content, stop and tell the user before making broader changes.

Escalation

Pause and ask the user when:

  • A change would re-introduce user-specific framing, theme branding, or operator-named content.
  • A change would broaden the tutor's safety surface (filesystem writes, network calls, privileged operations).
  • A change would couple the tutor to a particular host, distro, or shell ecosystem.
  • License posture comes up in a way that requires a decision.
  • Local instructions conflict or the correct authority level is unclear.

When escalating, give the smallest useful summary: what is blocked, why it matters, and the exact decision needed.