Italiano

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

AGENTS.md - Italian Trip Sprint Coach

Mission

You are Codex working inside Italian Trip Sprint Coach, a local-first web app that helps the user learn practical Italian before flying to Italy on 17 July 2026.

This is a deadline-driven MVP, not a generic language-learning SaaS and not a Duolingo clone.

Primary goal: help the user say useful Italian phrases in real travel situations.

Practical communication beats perfect grammar.

Do not add auth, billing, teams, cloud sync, analytics dashboards, subscriptions, or paid API dependencies unless the user explicitly asks.

Source Of Truth

Use this order:

1. Current user request.
2. Current source code and package.json.
3. Existing docs, if present.
4. Existing content/data files.
5. This AGENTS.md.

If this file conflicts with the actual repository, inspect the code and report the conflict.

Do not assume project structure. Inspect it.

Project Facts

• Product: Italian Trip Sprint Coach
• Deadline: 17 July 2026
• Main travel context: Italy, especially Bergamo unless the user changes it.
• UI language: Polish.
• Learning language: Italian.
• Explanations/translations: Polish.
• MVP should be local-first.
• Progress should persist with localStorage or IndexedDB.
• Prefer TypeScript.
• Prefer mobile-first responsive UI.
• Prefer local seed data in JSON/TS files.
• If Next.js App Router is present, preserve it.
• If Tailwind is present, preserve it.
• If another stack is already present, adapt to it instead of rewriting.

MVP Priorities

When tradeoffs are necessary, prioritize:

1. Useful travel content the user can practice today.
2. Working daily lesson flow.
3. Speaking/shadowing practice.
4. Review and spaced repetition.
5. Local progress persistence.
6. Mobile usability.
7. UI polish.
8. Architecture elegance.
9. Graphify freshness.

Core loop:

Dashboard → Today’s Lesson → Read + Listen → Speak Out Loud → Review → Travel Mission Progress

If this loop is broken, fix it before adding new features.

Default Build Order

For a fresh MVP, build in this order:

1. Project structure and routes.
2. Typed content model.
3. Seed content.
4. Dashboard with countdown.
5. Daily lesson flow.
6. Travel missions.
7. Read + Listen with TTS fallback.
8. Chunk Trainer.
9. Speaking Gym with fallback self-evaluation.
10. Local progress persistence.
11. Review/spaced repetition.
12. Bergamo Survival Mode.
13. UI polish.

Do not build advanced settings, accounts, backend infrastructure, sharing, admin panels, or analytics before the core learning loop works.

Learning Method

The app must use these learning principles:

• Teach phrases/chunks, not isolated vocabulary.
• Use real travel scenes, not school-style lessons.
• Combine reading + audio.
• Use short dialogues and mini-stories.
• Teach grammar only as optional rescue notes.
• Push early speaking with low pressure.
• Use active recall and spaced repetition.
• Use cognates/“Italian cheat codes” to reduce beginner stress.
• Make Italian part of the user’s daily trip prep.

Important chunk patterns:

• Vorrei...
• Posso avere...?
• Dov'è...?
• Quanto costa?
• Può ripetere?
• Può parlare più lentamente?
• Parlo solo un po' di italiano.
• Siamo in quattro.
• Abbiamo una prenotazione.
• Vorrei pagare con carta.

Each important phrase should include, when practical:

• Italian phrase,
• Polish translation,
• pronunciation help for Polish speakers,
• examples,
• mission/category,
• review-card support.

Travel Scope

Prioritize these situations:

• airport,
• transfer,
• hotel check-in,
• asking for directions,
• café,
• restaurant,
• bar,
• paying,
• tickets,
• transport,
• shopping,
• asking someone to repeat/speak slower,
• emergency/help,
• simple small talk.

Avoid low-value school topics unless they directly support travel communication.

Content Requirements

Expected MVP seed content:

• 80-120 useful travel phrases,
• 10 travel missions,
• 10 short dialogues,
• 10 mini-stories,
• 100 review cards,
• 30 cognates,
• 20 speaking tasks,
• 10 immersion micro-tasks.

Do not leave empty placeholders like TODO: add phrases.

Italian content must be:

• simple,
• natural,
• tourist-safe,
• short enough to remember,
• useful under stress,
• translated into Polish,
• grouped by situation,
• compatible with review cards.

Avoid:

• regional slang,
• advanced grammar-first lessons,
• rare literary phrases,
• unnatural literal translations from Polish,
• long abstract vocabulary lists,
• copied external course content.

When unsure, prefer simpler Italian. If content may need review, mark it with needsReview: true.

Copyright

Do not copy YouTube transcripts, blog posts, commercial course content, or app lessons into the project.

Use external material only as learning-method inspiration. Create original phrases, dialogues, stories, grammar notes, and review cards.

Core Modules

Build or preserve these modules:

• Dashboard
• Daily Lesson
• Travel Missions
• Chunk Trainer
• Read + Listen
• Speaking Gym
• Review / Spaced Repetition
• Grammar Rescue
• Pronunciation Lab
• Bergamo Survival Mode
• Local Progress

Data Model Guidance

Use simple typed models unless the project already has better ones.

Suggested entities:

• Phrase
• ChunkPattern
• Mission
• Dialogue
• Story
• ReviewCard
• UserProgress
• SpeakingExercise
• GrammarNote
• PronunciationDrill
• ImmersionTask

Suggested Phrase fields:

• id
• italian
• polish
• pronunciation
• missionId
• tags
• difficulty
• examples
• chunkPatternId
• needsReview

Suggested ReviewCard fields:

• id
• type
• prompt
• answer
• phraseId
• missionId
• dueAt
• interval
• ease
• lastReviewedAt

Keep the schema simple until the MVP loop works.

Audio And Speaking

Use Web Speech API where appropriate.

Use it-IT for Italian speech when possible.

Always provide fallbacks:

• If TTS fails, show text and pronunciation.
• If speech recognition fails, use self-evaluation.
• Never block learning because speech APIs are unavailable.

Speaking tasks should include:

• repeat after audio,
• answer a travel prompt,
• roleplay a mini-scene,
• optional record/listen if supported,
• self-rating if recognition is unavailable.

Grammar Rules

Do not make grammar the main path.

Grammar should be optional, short, and tied to phrases the user already saw.

Good topics:

• vorrei,
• posso,
• dov'è,
• un/una/il/la,
• basic word order,
• numbers/prices/time,
• essential verbs: essere, avere, volere, potere, andare, prendere, pagare.

Use labels like “Dlaczego tak?” or “Grammar Rescue”.

UI Rules

Mobile-first.

Use Polish UI copy.

Prioritize:

• large tap targets,
• clear hierarchy,
• low cognitive load,
• fast daily-use flow,
• visible progress,
• visible countdown to 17 July 2026,
• encouraging but practical tone.

Good UI phrases:

• “Powiedz to na głos”
• “Przetrwaj hotel”
• “Zamów jak człowiek”
• “Nie panikuj, powiedz to”
• “Włoski, który już znasz”
• “Bergamo Survival Mode”

Avoid dense academic screens.

Graphify

The user will not manually inspect the repository. Codex must navigate the project independently.

Use Graphify for non-trivial work:

• architecture-level tasks,
• multi-module changes,
• unfamiliar flows,
• broad debugging,
• dependency/call-path analysis,
• content model changes,
• progress/review scheduling changes,
• app-wide UI flows.

If graphify-out/graph.json exists:

• use graphify query "",
• use graphify explain "",
• use graphify path "" "" when useful.

If the graph is missing, incompatible, or clearly stale:

• run graphify update . if available,
• if needed, inspect graphify --help,
• do not ask the user to create the graph manually.

After meaningful multi-file changes, run graphify update . when available.

Do not use Graphify for tiny one-file edits, copy fixes, or obvious localized bugs.

If Graphify fails, fall back to targeted rg, focused file reads, and tests. Report the failure in Notes / risks. Do not pretend Graphify ran.

Subagent Policy

Small tasks stay in the parent thread.

Medium tasks may use one focused subagent.

Large tasks may use multiple subagents, max four concurrent threads.

The parent thread owns orchestration, integration, scope, file ownership, and final delivery.

No recursive delegation.

Only one write-capable agent may own a file or overlapping file set at a time.

Reviewers and validators are read-only.

Security reviewer is mandatory before commit or push.

Do not claim a subagent ran unless it actually ran.

Subagent Split

Use these roles for large tasks:

Product / Learning Architect

Owns product flow, daily lesson structure, missions, MVP priorities, and acceptance criteria.

Protects the travel-first MVP direction.

Italian Content Agent

Owns phrases, translations, dialogues, stories, grammar notes, pronunciation notes, and review-card content.

Prioritizes simple, natural, tourist-safe Italian.

Frontend / UX Agent

Owns Dashboard, Daily Lesson, Missions, Chunk Trainer, Read + Listen, Speaking Gym, Review, Survival Mode, responsive UI, and Polish copy.

Data / Progress Agent

Owns local persistence, review scheduling, streak, lesson completion, mission scores, and speaking confidence.

Audio / Speaking Agent

Owns TTS, shadowing, speech fallback, recording if implemented, and browser capability detection.

Graph / Architecture Navigator

Uses Graphify and targeted inspection to understand architecture and narrow implementation scope.

QA / Verification Agent

Owns tests, manual QA, acceptance criteria, persistence checks, mobile flow checks, and regression detection.

Security / Git Agent

Owns git status, diff review, secrets/dependency review, commit preparation, and push safety.

Implementation Rules

• Keep changes small and faithful to the request.
• Preserve existing architecture unless the user asks for a refactor.
• Use English identifiers in code and Polish labels in UI.
• Do not add speculative features.
• Do not add paid APIs unless explicitly requested.
• Do not add backend/auth/billing unless explicitly requested.
• Do not hardcode secrets, tokens, credentials, private URLs, or private data.
• Do not wipe user progress unless explicitly requested.
• Prefer local-first behavior.
• Keep content editing simple.
• Do not claim tools, tests, skills, hooks, validators, or Graphify ran unless they actually ran.

Verification

Run the narrowest relevant check first.

Recommended checks:

• TypeScript/build change: typecheck/build if available.
• UI change: lint/typecheck and inspect key route if possible.
• Content change: validate content structure and check for empty/malformed entries.
• Progress/review change: test refresh persistence and review scheduling.
• Audio/speaking change: test normal and fallback states.
• Large flow change: test Dashboard → Daily Lesson → Read + Listen → Speaking → Review → Mission.
• Multi-file architecture change: run graphify update . if available.

Always distinguish:

• passed checks,
• failures caused by the change,
• unrelated existing failures,
• checks not run and why.

Git And Security

No commit unless the user explicitly requests it.

No push without separate explicit approval.

Before commit:

• inspect git status --short,
• review intended diff,
• stage specific files only,
• run security review.

Never commit:

• .env,
• real credentials,
• API keys,
• tokens,
• private keys,
• local databases,
• logs,
• backups,
• private generated reports,
• user-specific global Codex configuration.

Final Response Format

For small and medium tasks:

Implemented: Changed files: Verification: Notes / risks:

For large tasks, also include:

Subagents used: Skills used: Graphify: Integration notes:

Keep final reports concise. Do not list agents/skills/tools that were not actually used.